mail360 data manager v2.1.0 installation and ... · • ftp agent: periodically checks a...

76
Ill PitneyBowes Bus. in ess I nsi ght --- ••••••••• / - ••••••• - -~----~-~ ___J- ••••••••••••• , \ - * •. • . • .• MAILSTREAM [CJ] '"' i - .... - ... Ill ...... . - * •• •• ••• MAILSTREAM / *' 1111 ' 11 .J .-"' ~~-~--=-=-~ •• ••• 0 =- = * : :.•:•:.:. MAILSTREAM - ••• •• - ----: ~--:- -- l :.•:•:.:. APPR , J1,ES PITNEY BO,"IES PITNEY BOWES• PITNEY BOi1ES PITNEr BO.VE,·' '< ",, S • ', "1, r, · T' -,,, r · ' C: 1 ', '",, ', ,8,, , ·' ', ,8,,[S PITNEY G01',[S ~. ,8,, S • PITNEY MAIL360 Data Manager™ Installation and Administration Guide Version 2.1.0 June 2010 www.g1.com/support

Upload: others

Post on 19-Jul-2020

0 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Ill PitneyBowes Busin ess Insight

--- bullbullbullbullbullbullbullbullbull - bullbullbullbullbullbullbull - -~----~-~ ___J- bullbullbullbullbullbullbullbullbullbullbullbullbull ~~ - bull bull bull bull MAILSTREAM [CJ] i - - ~ ~~ Ill ~ - bullbull bullbull bullbullbull bull MAILSTREAM 1111 bull bull 11 J - ~~-~--=-=-~ bullbull bullbullbull bull 0 =- = bullbull MAILSTREAM ~ - ~ bull bullbullbull bullbull - ~~~ ---- ~--- -- l bullbull APPR

J1ES bull PITNEY BOIES bull PITNEY BOWESbull PITNEY BOi1ES bull PITNEr BOVEmiddot lt S bull 1 r middot T - r middot C 1 bull bull 8 middot 8[S bull PITNEY G01[S bull ~ bull 8 S bull PITNEY

MAIL360 Data Managertrade Installation and Administration Guide

Version 210

June 2010

wwwg1comsupport

copy 2010 Pitney Bowes Software Inc

All rights reserved GROUP 1 the GROUP 1 logo Pitney Bowes and ldquoEngineering the flow of communicationrdquo are registered trademarks of Pitney Bowes Inc MAIL360 Data Manager is a trademark of Pitney Bowes Inc All other marks are trademarks or registered trademarks of their respective owners

Pitney Bowes Inc holds a non-exclusive license to publish and sell ZIP + 4reg databases on optical and magnetic media The following trademarks are owned by the United States Postal Service CASS CASS Certified First-Class Mail Intelligent Mail PLANET Code Postal Service POSTNET Post Office United States Postal Service Standard Mail United States Post Office USPS ZIP Code and ZIP + 4 This list is not exhaustive of the trademarks belonging to the Postal Service

Pitney Bowes Inc is a non-exclusive licensee of USPSreg for NCOALinkreg processing

Prices for Pitney Bowes Softwares products options and services are not established controlled or approved by USPSreg or United States Government When utilizing RDItrade data to determine parcel-shipping costs the business decision on which parcel delivery company to use is not made by the USPSreg or United States Government

AD 1207

PITNEY BOWES BUSINESS INSIGHT DOCUMENTATION DEPARTMENT 4200 PARLIAMENT PL STE 600 LANHAM MD 20706-1844

DIMD210WPINS

T A B L E O F C O N T E N T S

CHAPTER 1 PREPARING FOR YOUR MAIL360 DATA MANAGER INSTALLATION

Welcome to the MAIL360 Data Managertrade System 4 Installation and Configuration Overview 7 System Prerequisites 7 Information You Will Need 8

CHAPTER 2 SETTING UP YOUR MAIL360 DATA MANAGER DATABASES

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 14 Configuring SQL Server Reporting Services (SSRS) Security 14

CHAPTER 3 INSTALLING THE MAIL360 DATA MANAGERTM WEB SERVICES

Minimum Hardware Requirements 18 Installing MAIL360 Data Manager 18 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 26

Entering Your Subscriber ID 26 Importing and Configuring Your Unique Identity Certificate 27 Importing the Hub Identity Certificate 28 Importing the Hub Certificate Authorities 29

Uninstalling MAIL360 Data Manager 29 Uninstalling via the Uninstall Wizard 29 Uninstalling via Your Control Panel 30

CHAPTER 4 INSTALLING THE DATA MANAGER USER INTERFACE (UI) System Requirements 32 Installing the Web UI Software 32 Uninstalling the MAIL360 Data Manager UI 34

CHAPTER 5 CONFIGURING MAIL360 DATA MANAGER

Configuring the MAIL360 Report Manager and Scheduler 38 Configuring the MAIL360 Report Manager 38 Configuring the Scheduler 43

Additional Data Manager Configuration Options 45 Setting Permissions for MAIL360 Data Manager 46 Setting the Logging Level 47 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 1

CHAPTER 6 INSTALLING THE MAIL360 IDENTITY SERVER UI System Requirements 52 Installing the Web UI Software 52

CHAPTER 7 MAIL360 DATA MANAGER SECURITY

MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

Version 210June 2010 2

C H A P T E R 1

Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System 4 Installation and Configuration Overview 7 System Prerequisites 7 Information You Will Need 8

MAIL360 Data Managertrade Installation and Administration Guide 3

1 Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System

Before you proceed with your installation it may be helpful to understand the components of the MAIL360 Data Managertrade system and how they interact A high-level look at the Data Manager system is illustrated in Figure 1

Figure 1 MAIL360 Data Manager System

Version 210June 2010 4

Welcome to the MAIL360 Data Managertrade System 1

Figure 2 provides a more detailed look at the MAIL360 Data Manager components

Figure 2 MAIL360 Data Manager Components

The main components of the MAIL360 Data Manager system are described below

bull Client Bus Delivers messages to and from the different parts of the system In addition to what is shown in the diagram it also stores bus information in its own database and archives messages

bull Data Manager Service The main set of services used to submit and track mailpieces

bull Message Receiver Receives messages to communicate via the Client Bus Message Receiver also communicates with the Data Manager Hub (not pictured) to retrieve mailpiece event data

bull FTP Agent Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system Files can be placed in this input directory either via FTP server or by normal file copies

MAIL360 Data Managertrade Installation and Administration Guide 5

1 Preparing for Your MAIL360 Data Manager Installation

bull Report Manager Provides the reports service

bull Identity Server Added new module to handle user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull Scheduler Facility that provides for the periodic execution of tasks These include

ndash Hub Mailer ID Notifier mdash Notifies the MAIL360 Hub about mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used since the last invocation This facility is an administrative aide ensuring that the Hub administrators are able to keep USPS subscriptions and Hub routing information up to date

ndash DB Aggregator mdash Performs database pre-aggregation to support efficient report execution

The schedules for these activities are configured via the MAIL360 Data Manager Configuration utility

The MAIL360 Hub is also an instrumental part of the Data Manager system Data Manager will periodically notify the Hub of mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used recently This is done to ensure that events are being routed properly

NOTE The Web user interface (UI) may also be installed See Chapter 4 Installing the Data Manager User Interface (UI) for more information

Version 210June 2010 6

Installation and Configuration Overview 1

Installation and Configuration Overview

Here is a high-level look at the MAIL360 Data Manager installation process

1 Ensure that you meet the System Prerequisites for the installation

2 Gather the necessary information for completing the install process (See ldquoInformation You Will Needrdquo on page 8)

3 Set up your databases (See Chapter 2 Setting Up Your MAIL360 Data Manager Databases)

4 Install the Data Manager services (See Chapter 3 Installing the MAIL360 Data ManagerTM Web Services)

5 Configure the Data Manager hub subscription (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26)

6 Configure your MAIL360 Reports and Scheduler options if necessary using the Configuration Utility (See ldquoConfiguring the MAIL360 Report Manager and Schedulerrdquo on page 38)

7 Install the Data Manager User Interface if desired (See Chapter 4 Installing the Data Manager User Interface (UI))

System Prerequisites

The following items are required for your MAIL360 Data ManagerTM installation

bull Microsoftreg NET Framework 35 SP1 (available for download on the Microsoft Web site httpwwwmicrosoftcom) should be installed The Data Manager installer will assist with this if it is not already installed

bull Microsoftreg Message Queueing (MSMQ) must be installed

bull Microsoftreg SQL Serverreg 2008 Enterprise Edition databases and users must be available for use by the Data Manager services

NOTE If you will be using MAIL360 Data Manager with MAIL360 Server on the same database server you must have Enterprise Edition

bull Microsoftreg SQL Serverreg 2008 Reporting Services should be available for use

bull The Distributed Transaction Coordinator service must be started and Network DTC Access enabled before using the Data Manager system

bull Authentication certificates must be obtained from Pitney Bowes Business Insighttrade and installed before using the software (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26 for more information)

MAIL360 Data Managertrade Installation and Administration Guide 7

1 Preparing for Your MAIL360 Data Manager Installation

Information You Will Need

You should gather the following information before proceeding with your installation

bull Database information including server database and the Windows account under which the MAIL360 services will run

bull The ldquoaccess keyrdquo for temporary licensing of your Data Manager software (located on your packing slip)

bull Your Data Manager subscriber ID (obtained from Pitney Bowes Business Insight)

bull The location of the directory where your pre-installed IIS FTP service places received files (if applicable)

bull SMTP account setup information if using e-mail notification of mailpiece-file processing

bull The ldquoBridge Check Service URIrdquo (from Pitney Bowes Business Insight)

Version 210June 2010 8

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 2: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

copy 2010 Pitney Bowes Software Inc

All rights reserved GROUP 1 the GROUP 1 logo Pitney Bowes and ldquoEngineering the flow of communicationrdquo are registered trademarks of Pitney Bowes Inc MAIL360 Data Manager is a trademark of Pitney Bowes Inc All other marks are trademarks or registered trademarks of their respective owners

Pitney Bowes Inc holds a non-exclusive license to publish and sell ZIP + 4reg databases on optical and magnetic media The following trademarks are owned by the United States Postal Service CASS CASS Certified First-Class Mail Intelligent Mail PLANET Code Postal Service POSTNET Post Office United States Postal Service Standard Mail United States Post Office USPS ZIP Code and ZIP + 4 This list is not exhaustive of the trademarks belonging to the Postal Service

Pitney Bowes Inc is a non-exclusive licensee of USPSreg for NCOALinkreg processing

Prices for Pitney Bowes Softwares products options and services are not established controlled or approved by USPSreg or United States Government When utilizing RDItrade data to determine parcel-shipping costs the business decision on which parcel delivery company to use is not made by the USPSreg or United States Government

AD 1207

PITNEY BOWES BUSINESS INSIGHT DOCUMENTATION DEPARTMENT 4200 PARLIAMENT PL STE 600 LANHAM MD 20706-1844

DIMD210WPINS

T A B L E O F C O N T E N T S

CHAPTER 1 PREPARING FOR YOUR MAIL360 DATA MANAGER INSTALLATION

Welcome to the MAIL360 Data Managertrade System 4 Installation and Configuration Overview 7 System Prerequisites 7 Information You Will Need 8

CHAPTER 2 SETTING UP YOUR MAIL360 DATA MANAGER DATABASES

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 14 Configuring SQL Server Reporting Services (SSRS) Security 14

CHAPTER 3 INSTALLING THE MAIL360 DATA MANAGERTM WEB SERVICES

Minimum Hardware Requirements 18 Installing MAIL360 Data Manager 18 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 26

Entering Your Subscriber ID 26 Importing and Configuring Your Unique Identity Certificate 27 Importing the Hub Identity Certificate 28 Importing the Hub Certificate Authorities 29

Uninstalling MAIL360 Data Manager 29 Uninstalling via the Uninstall Wizard 29 Uninstalling via Your Control Panel 30

CHAPTER 4 INSTALLING THE DATA MANAGER USER INTERFACE (UI) System Requirements 32 Installing the Web UI Software 32 Uninstalling the MAIL360 Data Manager UI 34

CHAPTER 5 CONFIGURING MAIL360 DATA MANAGER

Configuring the MAIL360 Report Manager and Scheduler 38 Configuring the MAIL360 Report Manager 38 Configuring the Scheduler 43

Additional Data Manager Configuration Options 45 Setting Permissions for MAIL360 Data Manager 46 Setting the Logging Level 47 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 1

CHAPTER 6 INSTALLING THE MAIL360 IDENTITY SERVER UI System Requirements 52 Installing the Web UI Software 52

CHAPTER 7 MAIL360 DATA MANAGER SECURITY

MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

Version 210June 2010 2

C H A P T E R 1

Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System 4 Installation and Configuration Overview 7 System Prerequisites 7 Information You Will Need 8

MAIL360 Data Managertrade Installation and Administration Guide 3

1 Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System

Before you proceed with your installation it may be helpful to understand the components of the MAIL360 Data Managertrade system and how they interact A high-level look at the Data Manager system is illustrated in Figure 1

Figure 1 MAIL360 Data Manager System

Version 210June 2010 4

Welcome to the MAIL360 Data Managertrade System 1

Figure 2 provides a more detailed look at the MAIL360 Data Manager components

Figure 2 MAIL360 Data Manager Components

The main components of the MAIL360 Data Manager system are described below

bull Client Bus Delivers messages to and from the different parts of the system In addition to what is shown in the diagram it also stores bus information in its own database and archives messages

bull Data Manager Service The main set of services used to submit and track mailpieces

bull Message Receiver Receives messages to communicate via the Client Bus Message Receiver also communicates with the Data Manager Hub (not pictured) to retrieve mailpiece event data

bull FTP Agent Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system Files can be placed in this input directory either via FTP server or by normal file copies

MAIL360 Data Managertrade Installation and Administration Guide 5

1 Preparing for Your MAIL360 Data Manager Installation

bull Report Manager Provides the reports service

bull Identity Server Added new module to handle user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull Scheduler Facility that provides for the periodic execution of tasks These include

ndash Hub Mailer ID Notifier mdash Notifies the MAIL360 Hub about mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used since the last invocation This facility is an administrative aide ensuring that the Hub administrators are able to keep USPS subscriptions and Hub routing information up to date

ndash DB Aggregator mdash Performs database pre-aggregation to support efficient report execution

The schedules for these activities are configured via the MAIL360 Data Manager Configuration utility

The MAIL360 Hub is also an instrumental part of the Data Manager system Data Manager will periodically notify the Hub of mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used recently This is done to ensure that events are being routed properly

NOTE The Web user interface (UI) may also be installed See Chapter 4 Installing the Data Manager User Interface (UI) for more information

Version 210June 2010 6

Installation and Configuration Overview 1

Installation and Configuration Overview

Here is a high-level look at the MAIL360 Data Manager installation process

1 Ensure that you meet the System Prerequisites for the installation

2 Gather the necessary information for completing the install process (See ldquoInformation You Will Needrdquo on page 8)

3 Set up your databases (See Chapter 2 Setting Up Your MAIL360 Data Manager Databases)

4 Install the Data Manager services (See Chapter 3 Installing the MAIL360 Data ManagerTM Web Services)

5 Configure the Data Manager hub subscription (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26)

6 Configure your MAIL360 Reports and Scheduler options if necessary using the Configuration Utility (See ldquoConfiguring the MAIL360 Report Manager and Schedulerrdquo on page 38)

7 Install the Data Manager User Interface if desired (See Chapter 4 Installing the Data Manager User Interface (UI))

System Prerequisites

The following items are required for your MAIL360 Data ManagerTM installation

bull Microsoftreg NET Framework 35 SP1 (available for download on the Microsoft Web site httpwwwmicrosoftcom) should be installed The Data Manager installer will assist with this if it is not already installed

bull Microsoftreg Message Queueing (MSMQ) must be installed

bull Microsoftreg SQL Serverreg 2008 Enterprise Edition databases and users must be available for use by the Data Manager services

NOTE If you will be using MAIL360 Data Manager with MAIL360 Server on the same database server you must have Enterprise Edition

bull Microsoftreg SQL Serverreg 2008 Reporting Services should be available for use

bull The Distributed Transaction Coordinator service must be started and Network DTC Access enabled before using the Data Manager system

bull Authentication certificates must be obtained from Pitney Bowes Business Insighttrade and installed before using the software (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26 for more information)

MAIL360 Data Managertrade Installation and Administration Guide 7

1 Preparing for Your MAIL360 Data Manager Installation

Information You Will Need

You should gather the following information before proceeding with your installation

bull Database information including server database and the Windows account under which the MAIL360 services will run

bull The ldquoaccess keyrdquo for temporary licensing of your Data Manager software (located on your packing slip)

bull Your Data Manager subscriber ID (obtained from Pitney Bowes Business Insight)

bull The location of the directory where your pre-installed IIS FTP service places received files (if applicable)

bull SMTP account setup information if using e-mail notification of mailpiece-file processing

bull The ldquoBridge Check Service URIrdquo (from Pitney Bowes Business Insight)

Version 210June 2010 8

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 3: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

T A B L E O F C O N T E N T S

CHAPTER 1 PREPARING FOR YOUR MAIL360 DATA MANAGER INSTALLATION

Welcome to the MAIL360 Data Managertrade System 4 Installation and Configuration Overview 7 System Prerequisites 7 Information You Will Need 8

CHAPTER 2 SETTING UP YOUR MAIL360 DATA MANAGER DATABASES

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 14 Configuring SQL Server Reporting Services (SSRS) Security 14

CHAPTER 3 INSTALLING THE MAIL360 DATA MANAGERTM WEB SERVICES

Minimum Hardware Requirements 18 Installing MAIL360 Data Manager 18 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 26

Entering Your Subscriber ID 26 Importing and Configuring Your Unique Identity Certificate 27 Importing the Hub Identity Certificate 28 Importing the Hub Certificate Authorities 29

Uninstalling MAIL360 Data Manager 29 Uninstalling via the Uninstall Wizard 29 Uninstalling via Your Control Panel 30

CHAPTER 4 INSTALLING THE DATA MANAGER USER INTERFACE (UI) System Requirements 32 Installing the Web UI Software 32 Uninstalling the MAIL360 Data Manager UI 34

CHAPTER 5 CONFIGURING MAIL360 DATA MANAGER

Configuring the MAIL360 Report Manager and Scheduler 38 Configuring the MAIL360 Report Manager 38 Configuring the Scheduler 43

Additional Data Manager Configuration Options 45 Setting Permissions for MAIL360 Data Manager 46 Setting the Logging Level 47 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 1

CHAPTER 6 INSTALLING THE MAIL360 IDENTITY SERVER UI System Requirements 52 Installing the Web UI Software 52

CHAPTER 7 MAIL360 DATA MANAGER SECURITY

MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

Version 210June 2010 2

C H A P T E R 1

Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System 4 Installation and Configuration Overview 7 System Prerequisites 7 Information You Will Need 8

MAIL360 Data Managertrade Installation and Administration Guide 3

1 Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System

Before you proceed with your installation it may be helpful to understand the components of the MAIL360 Data Managertrade system and how they interact A high-level look at the Data Manager system is illustrated in Figure 1

Figure 1 MAIL360 Data Manager System

Version 210June 2010 4

Welcome to the MAIL360 Data Managertrade System 1

Figure 2 provides a more detailed look at the MAIL360 Data Manager components

Figure 2 MAIL360 Data Manager Components

The main components of the MAIL360 Data Manager system are described below

bull Client Bus Delivers messages to and from the different parts of the system In addition to what is shown in the diagram it also stores bus information in its own database and archives messages

bull Data Manager Service The main set of services used to submit and track mailpieces

bull Message Receiver Receives messages to communicate via the Client Bus Message Receiver also communicates with the Data Manager Hub (not pictured) to retrieve mailpiece event data

bull FTP Agent Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system Files can be placed in this input directory either via FTP server or by normal file copies

MAIL360 Data Managertrade Installation and Administration Guide 5

1 Preparing for Your MAIL360 Data Manager Installation

bull Report Manager Provides the reports service

bull Identity Server Added new module to handle user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull Scheduler Facility that provides for the periodic execution of tasks These include

ndash Hub Mailer ID Notifier mdash Notifies the MAIL360 Hub about mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used since the last invocation This facility is an administrative aide ensuring that the Hub administrators are able to keep USPS subscriptions and Hub routing information up to date

ndash DB Aggregator mdash Performs database pre-aggregation to support efficient report execution

The schedules for these activities are configured via the MAIL360 Data Manager Configuration utility

The MAIL360 Hub is also an instrumental part of the Data Manager system Data Manager will periodically notify the Hub of mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used recently This is done to ensure that events are being routed properly

NOTE The Web user interface (UI) may also be installed See Chapter 4 Installing the Data Manager User Interface (UI) for more information

Version 210June 2010 6

Installation and Configuration Overview 1

Installation and Configuration Overview

Here is a high-level look at the MAIL360 Data Manager installation process

1 Ensure that you meet the System Prerequisites for the installation

2 Gather the necessary information for completing the install process (See ldquoInformation You Will Needrdquo on page 8)

3 Set up your databases (See Chapter 2 Setting Up Your MAIL360 Data Manager Databases)

4 Install the Data Manager services (See Chapter 3 Installing the MAIL360 Data ManagerTM Web Services)

5 Configure the Data Manager hub subscription (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26)

6 Configure your MAIL360 Reports and Scheduler options if necessary using the Configuration Utility (See ldquoConfiguring the MAIL360 Report Manager and Schedulerrdquo on page 38)

7 Install the Data Manager User Interface if desired (See Chapter 4 Installing the Data Manager User Interface (UI))

System Prerequisites

The following items are required for your MAIL360 Data ManagerTM installation

bull Microsoftreg NET Framework 35 SP1 (available for download on the Microsoft Web site httpwwwmicrosoftcom) should be installed The Data Manager installer will assist with this if it is not already installed

bull Microsoftreg Message Queueing (MSMQ) must be installed

bull Microsoftreg SQL Serverreg 2008 Enterprise Edition databases and users must be available for use by the Data Manager services

NOTE If you will be using MAIL360 Data Manager with MAIL360 Server on the same database server you must have Enterprise Edition

bull Microsoftreg SQL Serverreg 2008 Reporting Services should be available for use

bull The Distributed Transaction Coordinator service must be started and Network DTC Access enabled before using the Data Manager system

bull Authentication certificates must be obtained from Pitney Bowes Business Insighttrade and installed before using the software (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26 for more information)

MAIL360 Data Managertrade Installation and Administration Guide 7

1 Preparing for Your MAIL360 Data Manager Installation

Information You Will Need

You should gather the following information before proceeding with your installation

bull Database information including server database and the Windows account under which the MAIL360 services will run

bull The ldquoaccess keyrdquo for temporary licensing of your Data Manager software (located on your packing slip)

bull Your Data Manager subscriber ID (obtained from Pitney Bowes Business Insight)

bull The location of the directory where your pre-installed IIS FTP service places received files (if applicable)

bull SMTP account setup information if using e-mail notification of mailpiece-file processing

bull The ldquoBridge Check Service URIrdquo (from Pitney Bowes Business Insight)

Version 210June 2010 8

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 4: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

CHAPTER 6 INSTALLING THE MAIL360 IDENTITY SERVER UI System Requirements 52 Installing the Web UI Software 52

CHAPTER 7 MAIL360 DATA MANAGER SECURITY

MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

Version 210June 2010 2

C H A P T E R 1

Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System 4 Installation and Configuration Overview 7 System Prerequisites 7 Information You Will Need 8

MAIL360 Data Managertrade Installation and Administration Guide 3

1 Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System

Before you proceed with your installation it may be helpful to understand the components of the MAIL360 Data Managertrade system and how they interact A high-level look at the Data Manager system is illustrated in Figure 1

Figure 1 MAIL360 Data Manager System

Version 210June 2010 4

Welcome to the MAIL360 Data Managertrade System 1

Figure 2 provides a more detailed look at the MAIL360 Data Manager components

Figure 2 MAIL360 Data Manager Components

The main components of the MAIL360 Data Manager system are described below

bull Client Bus Delivers messages to and from the different parts of the system In addition to what is shown in the diagram it also stores bus information in its own database and archives messages

bull Data Manager Service The main set of services used to submit and track mailpieces

bull Message Receiver Receives messages to communicate via the Client Bus Message Receiver also communicates with the Data Manager Hub (not pictured) to retrieve mailpiece event data

bull FTP Agent Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system Files can be placed in this input directory either via FTP server or by normal file copies

MAIL360 Data Managertrade Installation and Administration Guide 5

1 Preparing for Your MAIL360 Data Manager Installation

bull Report Manager Provides the reports service

bull Identity Server Added new module to handle user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull Scheduler Facility that provides for the periodic execution of tasks These include

ndash Hub Mailer ID Notifier mdash Notifies the MAIL360 Hub about mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used since the last invocation This facility is an administrative aide ensuring that the Hub administrators are able to keep USPS subscriptions and Hub routing information up to date

ndash DB Aggregator mdash Performs database pre-aggregation to support efficient report execution

The schedules for these activities are configured via the MAIL360 Data Manager Configuration utility

The MAIL360 Hub is also an instrumental part of the Data Manager system Data Manager will periodically notify the Hub of mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used recently This is done to ensure that events are being routed properly

NOTE The Web user interface (UI) may also be installed See Chapter 4 Installing the Data Manager User Interface (UI) for more information

Version 210June 2010 6

Installation and Configuration Overview 1

Installation and Configuration Overview

Here is a high-level look at the MAIL360 Data Manager installation process

1 Ensure that you meet the System Prerequisites for the installation

2 Gather the necessary information for completing the install process (See ldquoInformation You Will Needrdquo on page 8)

3 Set up your databases (See Chapter 2 Setting Up Your MAIL360 Data Manager Databases)

4 Install the Data Manager services (See Chapter 3 Installing the MAIL360 Data ManagerTM Web Services)

5 Configure the Data Manager hub subscription (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26)

6 Configure your MAIL360 Reports and Scheduler options if necessary using the Configuration Utility (See ldquoConfiguring the MAIL360 Report Manager and Schedulerrdquo on page 38)

7 Install the Data Manager User Interface if desired (See Chapter 4 Installing the Data Manager User Interface (UI))

System Prerequisites

The following items are required for your MAIL360 Data ManagerTM installation

bull Microsoftreg NET Framework 35 SP1 (available for download on the Microsoft Web site httpwwwmicrosoftcom) should be installed The Data Manager installer will assist with this if it is not already installed

bull Microsoftreg Message Queueing (MSMQ) must be installed

bull Microsoftreg SQL Serverreg 2008 Enterprise Edition databases and users must be available for use by the Data Manager services

NOTE If you will be using MAIL360 Data Manager with MAIL360 Server on the same database server you must have Enterprise Edition

bull Microsoftreg SQL Serverreg 2008 Reporting Services should be available for use

bull The Distributed Transaction Coordinator service must be started and Network DTC Access enabled before using the Data Manager system

bull Authentication certificates must be obtained from Pitney Bowes Business Insighttrade and installed before using the software (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26 for more information)

MAIL360 Data Managertrade Installation and Administration Guide 7

1 Preparing for Your MAIL360 Data Manager Installation

Information You Will Need

You should gather the following information before proceeding with your installation

bull Database information including server database and the Windows account under which the MAIL360 services will run

bull The ldquoaccess keyrdquo for temporary licensing of your Data Manager software (located on your packing slip)

bull Your Data Manager subscriber ID (obtained from Pitney Bowes Business Insight)

bull The location of the directory where your pre-installed IIS FTP service places received files (if applicable)

bull SMTP account setup information if using e-mail notification of mailpiece-file processing

bull The ldquoBridge Check Service URIrdquo (from Pitney Bowes Business Insight)

Version 210June 2010 8

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 5: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

C H A P T E R 1

Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System 4 Installation and Configuration Overview 7 System Prerequisites 7 Information You Will Need 8

MAIL360 Data Managertrade Installation and Administration Guide 3

1 Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System

Before you proceed with your installation it may be helpful to understand the components of the MAIL360 Data Managertrade system and how they interact A high-level look at the Data Manager system is illustrated in Figure 1

Figure 1 MAIL360 Data Manager System

Version 210June 2010 4

Welcome to the MAIL360 Data Managertrade System 1

Figure 2 provides a more detailed look at the MAIL360 Data Manager components

Figure 2 MAIL360 Data Manager Components

The main components of the MAIL360 Data Manager system are described below

bull Client Bus Delivers messages to and from the different parts of the system In addition to what is shown in the diagram it also stores bus information in its own database and archives messages

bull Data Manager Service The main set of services used to submit and track mailpieces

bull Message Receiver Receives messages to communicate via the Client Bus Message Receiver also communicates with the Data Manager Hub (not pictured) to retrieve mailpiece event data

bull FTP Agent Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system Files can be placed in this input directory either via FTP server or by normal file copies

MAIL360 Data Managertrade Installation and Administration Guide 5

1 Preparing for Your MAIL360 Data Manager Installation

bull Report Manager Provides the reports service

bull Identity Server Added new module to handle user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull Scheduler Facility that provides for the periodic execution of tasks These include

ndash Hub Mailer ID Notifier mdash Notifies the MAIL360 Hub about mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used since the last invocation This facility is an administrative aide ensuring that the Hub administrators are able to keep USPS subscriptions and Hub routing information up to date

ndash DB Aggregator mdash Performs database pre-aggregation to support efficient report execution

The schedules for these activities are configured via the MAIL360 Data Manager Configuration utility

The MAIL360 Hub is also an instrumental part of the Data Manager system Data Manager will periodically notify the Hub of mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used recently This is done to ensure that events are being routed properly

NOTE The Web user interface (UI) may also be installed See Chapter 4 Installing the Data Manager User Interface (UI) for more information

Version 210June 2010 6

Installation and Configuration Overview 1

Installation and Configuration Overview

Here is a high-level look at the MAIL360 Data Manager installation process

1 Ensure that you meet the System Prerequisites for the installation

2 Gather the necessary information for completing the install process (See ldquoInformation You Will Needrdquo on page 8)

3 Set up your databases (See Chapter 2 Setting Up Your MAIL360 Data Manager Databases)

4 Install the Data Manager services (See Chapter 3 Installing the MAIL360 Data ManagerTM Web Services)

5 Configure the Data Manager hub subscription (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26)

6 Configure your MAIL360 Reports and Scheduler options if necessary using the Configuration Utility (See ldquoConfiguring the MAIL360 Report Manager and Schedulerrdquo on page 38)

7 Install the Data Manager User Interface if desired (See Chapter 4 Installing the Data Manager User Interface (UI))

System Prerequisites

The following items are required for your MAIL360 Data ManagerTM installation

bull Microsoftreg NET Framework 35 SP1 (available for download on the Microsoft Web site httpwwwmicrosoftcom) should be installed The Data Manager installer will assist with this if it is not already installed

bull Microsoftreg Message Queueing (MSMQ) must be installed

bull Microsoftreg SQL Serverreg 2008 Enterprise Edition databases and users must be available for use by the Data Manager services

NOTE If you will be using MAIL360 Data Manager with MAIL360 Server on the same database server you must have Enterprise Edition

bull Microsoftreg SQL Serverreg 2008 Reporting Services should be available for use

bull The Distributed Transaction Coordinator service must be started and Network DTC Access enabled before using the Data Manager system

bull Authentication certificates must be obtained from Pitney Bowes Business Insighttrade and installed before using the software (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26 for more information)

MAIL360 Data Managertrade Installation and Administration Guide 7

1 Preparing for Your MAIL360 Data Manager Installation

Information You Will Need

You should gather the following information before proceeding with your installation

bull Database information including server database and the Windows account under which the MAIL360 services will run

bull The ldquoaccess keyrdquo for temporary licensing of your Data Manager software (located on your packing slip)

bull Your Data Manager subscriber ID (obtained from Pitney Bowes Business Insight)

bull The location of the directory where your pre-installed IIS FTP service places received files (if applicable)

bull SMTP account setup information if using e-mail notification of mailpiece-file processing

bull The ldquoBridge Check Service URIrdquo (from Pitney Bowes Business Insight)

Version 210June 2010 8

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 6: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

1 Preparing for Your MAIL360 Data Manager Installation

Welcome to the MAIL360 Data Managertrade System

Before you proceed with your installation it may be helpful to understand the components of the MAIL360 Data Managertrade system and how they interact A high-level look at the Data Manager system is illustrated in Figure 1

Figure 1 MAIL360 Data Manager System

Version 210June 2010 4

Welcome to the MAIL360 Data Managertrade System 1

Figure 2 provides a more detailed look at the MAIL360 Data Manager components

Figure 2 MAIL360 Data Manager Components

The main components of the MAIL360 Data Manager system are described below

bull Client Bus Delivers messages to and from the different parts of the system In addition to what is shown in the diagram it also stores bus information in its own database and archives messages

bull Data Manager Service The main set of services used to submit and track mailpieces

bull Message Receiver Receives messages to communicate via the Client Bus Message Receiver also communicates with the Data Manager Hub (not pictured) to retrieve mailpiece event data

bull FTP Agent Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system Files can be placed in this input directory either via FTP server or by normal file copies

MAIL360 Data Managertrade Installation and Administration Guide 5

1 Preparing for Your MAIL360 Data Manager Installation

bull Report Manager Provides the reports service

bull Identity Server Added new module to handle user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull Scheduler Facility that provides for the periodic execution of tasks These include

ndash Hub Mailer ID Notifier mdash Notifies the MAIL360 Hub about mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used since the last invocation This facility is an administrative aide ensuring that the Hub administrators are able to keep USPS subscriptions and Hub routing information up to date

ndash DB Aggregator mdash Performs database pre-aggregation to support efficient report execution

The schedules for these activities are configured via the MAIL360 Data Manager Configuration utility

The MAIL360 Hub is also an instrumental part of the Data Manager system Data Manager will periodically notify the Hub of mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used recently This is done to ensure that events are being routed properly

NOTE The Web user interface (UI) may also be installed See Chapter 4 Installing the Data Manager User Interface (UI) for more information

Version 210June 2010 6

Installation and Configuration Overview 1

Installation and Configuration Overview

Here is a high-level look at the MAIL360 Data Manager installation process

1 Ensure that you meet the System Prerequisites for the installation

2 Gather the necessary information for completing the install process (See ldquoInformation You Will Needrdquo on page 8)

3 Set up your databases (See Chapter 2 Setting Up Your MAIL360 Data Manager Databases)

4 Install the Data Manager services (See Chapter 3 Installing the MAIL360 Data ManagerTM Web Services)

5 Configure the Data Manager hub subscription (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26)

6 Configure your MAIL360 Reports and Scheduler options if necessary using the Configuration Utility (See ldquoConfiguring the MAIL360 Report Manager and Schedulerrdquo on page 38)

7 Install the Data Manager User Interface if desired (See Chapter 4 Installing the Data Manager User Interface (UI))

System Prerequisites

The following items are required for your MAIL360 Data ManagerTM installation

bull Microsoftreg NET Framework 35 SP1 (available for download on the Microsoft Web site httpwwwmicrosoftcom) should be installed The Data Manager installer will assist with this if it is not already installed

bull Microsoftreg Message Queueing (MSMQ) must be installed

bull Microsoftreg SQL Serverreg 2008 Enterprise Edition databases and users must be available for use by the Data Manager services

NOTE If you will be using MAIL360 Data Manager with MAIL360 Server on the same database server you must have Enterprise Edition

bull Microsoftreg SQL Serverreg 2008 Reporting Services should be available for use

bull The Distributed Transaction Coordinator service must be started and Network DTC Access enabled before using the Data Manager system

bull Authentication certificates must be obtained from Pitney Bowes Business Insighttrade and installed before using the software (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26 for more information)

MAIL360 Data Managertrade Installation and Administration Guide 7

1 Preparing for Your MAIL360 Data Manager Installation

Information You Will Need

You should gather the following information before proceeding with your installation

bull Database information including server database and the Windows account under which the MAIL360 services will run

bull The ldquoaccess keyrdquo for temporary licensing of your Data Manager software (located on your packing slip)

bull Your Data Manager subscriber ID (obtained from Pitney Bowes Business Insight)

bull The location of the directory where your pre-installed IIS FTP service places received files (if applicable)

bull SMTP account setup information if using e-mail notification of mailpiece-file processing

bull The ldquoBridge Check Service URIrdquo (from Pitney Bowes Business Insight)

Version 210June 2010 8

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 7: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Welcome to the MAIL360 Data Managertrade System 1

Figure 2 provides a more detailed look at the MAIL360 Data Manager components

Figure 2 MAIL360 Data Manager Components

The main components of the MAIL360 Data Manager system are described below

bull Client Bus Delivers messages to and from the different parts of the system In addition to what is shown in the diagram it also stores bus information in its own database and archives messages

bull Data Manager Service The main set of services used to submit and track mailpieces

bull Message Receiver Receives messages to communicate via the Client Bus Message Receiver also communicates with the Data Manager Hub (not pictured) to retrieve mailpiece event data

bull FTP Agent Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system Files can be placed in this input directory either via FTP server or by normal file copies

MAIL360 Data Managertrade Installation and Administration Guide 5

1 Preparing for Your MAIL360 Data Manager Installation

bull Report Manager Provides the reports service

bull Identity Server Added new module to handle user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull Scheduler Facility that provides for the periodic execution of tasks These include

ndash Hub Mailer ID Notifier mdash Notifies the MAIL360 Hub about mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used since the last invocation This facility is an administrative aide ensuring that the Hub administrators are able to keep USPS subscriptions and Hub routing information up to date

ndash DB Aggregator mdash Performs database pre-aggregation to support efficient report execution

The schedules for these activities are configured via the MAIL360 Data Manager Configuration utility

The MAIL360 Hub is also an instrumental part of the Data Manager system Data Manager will periodically notify the Hub of mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used recently This is done to ensure that events are being routed properly

NOTE The Web user interface (UI) may also be installed See Chapter 4 Installing the Data Manager User Interface (UI) for more information

Version 210June 2010 6

Installation and Configuration Overview 1

Installation and Configuration Overview

Here is a high-level look at the MAIL360 Data Manager installation process

1 Ensure that you meet the System Prerequisites for the installation

2 Gather the necessary information for completing the install process (See ldquoInformation You Will Needrdquo on page 8)

3 Set up your databases (See Chapter 2 Setting Up Your MAIL360 Data Manager Databases)

4 Install the Data Manager services (See Chapter 3 Installing the MAIL360 Data ManagerTM Web Services)

5 Configure the Data Manager hub subscription (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26)

6 Configure your MAIL360 Reports and Scheduler options if necessary using the Configuration Utility (See ldquoConfiguring the MAIL360 Report Manager and Schedulerrdquo on page 38)

7 Install the Data Manager User Interface if desired (See Chapter 4 Installing the Data Manager User Interface (UI))

System Prerequisites

The following items are required for your MAIL360 Data ManagerTM installation

bull Microsoftreg NET Framework 35 SP1 (available for download on the Microsoft Web site httpwwwmicrosoftcom) should be installed The Data Manager installer will assist with this if it is not already installed

bull Microsoftreg Message Queueing (MSMQ) must be installed

bull Microsoftreg SQL Serverreg 2008 Enterprise Edition databases and users must be available for use by the Data Manager services

NOTE If you will be using MAIL360 Data Manager with MAIL360 Server on the same database server you must have Enterprise Edition

bull Microsoftreg SQL Serverreg 2008 Reporting Services should be available for use

bull The Distributed Transaction Coordinator service must be started and Network DTC Access enabled before using the Data Manager system

bull Authentication certificates must be obtained from Pitney Bowes Business Insighttrade and installed before using the software (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26 for more information)

MAIL360 Data Managertrade Installation and Administration Guide 7

1 Preparing for Your MAIL360 Data Manager Installation

Information You Will Need

You should gather the following information before proceeding with your installation

bull Database information including server database and the Windows account under which the MAIL360 services will run

bull The ldquoaccess keyrdquo for temporary licensing of your Data Manager software (located on your packing slip)

bull Your Data Manager subscriber ID (obtained from Pitney Bowes Business Insight)

bull The location of the directory where your pre-installed IIS FTP service places received files (if applicable)

bull SMTP account setup information if using e-mail notification of mailpiece-file processing

bull The ldquoBridge Check Service URIrdquo (from Pitney Bowes Business Insight)

Version 210June 2010 8

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 8: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

1 Preparing for Your MAIL360 Data Manager Installation

bull Report Manager Provides the reports service

bull Identity Server Added new module to handle user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull Scheduler Facility that provides for the periodic execution of tasks These include

ndash Hub Mailer ID Notifier mdash Notifies the MAIL360 Hub about mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used since the last invocation This facility is an administrative aide ensuring that the Hub administrators are able to keep USPS subscriptions and Hub routing information up to date

ndash DB Aggregator mdash Performs database pre-aggregation to support efficient report execution

The schedules for these activities are configured via the MAIL360 Data Manager Configuration utility

The MAIL360 Hub is also an instrumental part of the Data Manager system Data Manager will periodically notify the Hub of mailer IDs (for outbound mailpieces) and routing codes (for remit mailpieces) that have been used recently This is done to ensure that events are being routed properly

NOTE The Web user interface (UI) may also be installed See Chapter 4 Installing the Data Manager User Interface (UI) for more information

Version 210June 2010 6

Installation and Configuration Overview 1

Installation and Configuration Overview

Here is a high-level look at the MAIL360 Data Manager installation process

1 Ensure that you meet the System Prerequisites for the installation

2 Gather the necessary information for completing the install process (See ldquoInformation You Will Needrdquo on page 8)

3 Set up your databases (See Chapter 2 Setting Up Your MAIL360 Data Manager Databases)

4 Install the Data Manager services (See Chapter 3 Installing the MAIL360 Data ManagerTM Web Services)

5 Configure the Data Manager hub subscription (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26)

6 Configure your MAIL360 Reports and Scheduler options if necessary using the Configuration Utility (See ldquoConfiguring the MAIL360 Report Manager and Schedulerrdquo on page 38)

7 Install the Data Manager User Interface if desired (See Chapter 4 Installing the Data Manager User Interface (UI))

System Prerequisites

The following items are required for your MAIL360 Data ManagerTM installation

bull Microsoftreg NET Framework 35 SP1 (available for download on the Microsoft Web site httpwwwmicrosoftcom) should be installed The Data Manager installer will assist with this if it is not already installed

bull Microsoftreg Message Queueing (MSMQ) must be installed

bull Microsoftreg SQL Serverreg 2008 Enterprise Edition databases and users must be available for use by the Data Manager services

NOTE If you will be using MAIL360 Data Manager with MAIL360 Server on the same database server you must have Enterprise Edition

bull Microsoftreg SQL Serverreg 2008 Reporting Services should be available for use

bull The Distributed Transaction Coordinator service must be started and Network DTC Access enabled before using the Data Manager system

bull Authentication certificates must be obtained from Pitney Bowes Business Insighttrade and installed before using the software (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26 for more information)

MAIL360 Data Managertrade Installation and Administration Guide 7

1 Preparing for Your MAIL360 Data Manager Installation

Information You Will Need

You should gather the following information before proceeding with your installation

bull Database information including server database and the Windows account under which the MAIL360 services will run

bull The ldquoaccess keyrdquo for temporary licensing of your Data Manager software (located on your packing slip)

bull Your Data Manager subscriber ID (obtained from Pitney Bowes Business Insight)

bull The location of the directory where your pre-installed IIS FTP service places received files (if applicable)

bull SMTP account setup information if using e-mail notification of mailpiece-file processing

bull The ldquoBridge Check Service URIrdquo (from Pitney Bowes Business Insight)

Version 210June 2010 8

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 9: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Installation and Configuration Overview 1

Installation and Configuration Overview

Here is a high-level look at the MAIL360 Data Manager installation process

1 Ensure that you meet the System Prerequisites for the installation

2 Gather the necessary information for completing the install process (See ldquoInformation You Will Needrdquo on page 8)

3 Set up your databases (See Chapter 2 Setting Up Your MAIL360 Data Manager Databases)

4 Install the Data Manager services (See Chapter 3 Installing the MAIL360 Data ManagerTM Web Services)

5 Configure the Data Manager hub subscription (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26)

6 Configure your MAIL360 Reports and Scheduler options if necessary using the Configuration Utility (See ldquoConfiguring the MAIL360 Report Manager and Schedulerrdquo on page 38)

7 Install the Data Manager User Interface if desired (See Chapter 4 Installing the Data Manager User Interface (UI))

System Prerequisites

The following items are required for your MAIL360 Data ManagerTM installation

bull Microsoftreg NET Framework 35 SP1 (available for download on the Microsoft Web site httpwwwmicrosoftcom) should be installed The Data Manager installer will assist with this if it is not already installed

bull Microsoftreg Message Queueing (MSMQ) must be installed

bull Microsoftreg SQL Serverreg 2008 Enterprise Edition databases and users must be available for use by the Data Manager services

NOTE If you will be using MAIL360 Data Manager with MAIL360 Server on the same database server you must have Enterprise Edition

bull Microsoftreg SQL Serverreg 2008 Reporting Services should be available for use

bull The Distributed Transaction Coordinator service must be started and Network DTC Access enabled before using the Data Manager system

bull Authentication certificates must be obtained from Pitney Bowes Business Insighttrade and installed before using the software (See ldquoConfiguring Your Data Manager Hub Subscriptionrdquo on page 26 for more information)

MAIL360 Data Managertrade Installation and Administration Guide 7

1 Preparing for Your MAIL360 Data Manager Installation

Information You Will Need

You should gather the following information before proceeding with your installation

bull Database information including server database and the Windows account under which the MAIL360 services will run

bull The ldquoaccess keyrdquo for temporary licensing of your Data Manager software (located on your packing slip)

bull Your Data Manager subscriber ID (obtained from Pitney Bowes Business Insight)

bull The location of the directory where your pre-installed IIS FTP service places received files (if applicable)

bull SMTP account setup information if using e-mail notification of mailpiece-file processing

bull The ldquoBridge Check Service URIrdquo (from Pitney Bowes Business Insight)

Version 210June 2010 8

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 10: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

1 Preparing for Your MAIL360 Data Manager Installation

Information You Will Need

You should gather the following information before proceeding with your installation

bull Database information including server database and the Windows account under which the MAIL360 services will run

bull The ldquoaccess keyrdquo for temporary licensing of your Data Manager software (located on your packing slip)

bull Your Data Manager subscriber ID (obtained from Pitney Bowes Business Insight)

bull The location of the directory where your pre-installed IIS FTP service places received files (if applicable)

bull SMTP account setup information if using e-mail notification of mailpiece-file processing

bull The ldquoBridge Check Service URIrdquo (from Pitney Bowes Business Insight)

Version 210June 2010 8

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 11: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

C H A P T E R 2

Setting Up Your MAIL360 Data Manager Databases

Prerequisites 10 Hardware Requirements 10 Setting Up Your Databases 10 Partitioning Your Data Manager Database 11

Partition Function 11 Partition Scheme (File Groups) 12

Running the Scripts for the Data Manager Database 13 Running the Scripts for the Client Bus Database 13 Configuring SQL Server Reporting Services (SSRS) Security 15

MAIL360 Data Managertrade Installation and Administration Guide 9

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 12: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

2 Setting Up Your MAIL360 Data Manager Databases

Prerequisites

The following items are required for the MAIL360 Data Manager database environment

bull Microsoft SQL Server 2008 Enterprise Edition including Reporting Services

bull The Distributed Transaction Coordinator Service must be started and network DTC Access enabled

Hardware Requirements

SQL Server hardware requirements depend on the size and usage of the data as well as any high availability requirements As a very rough guide for disk allow 15 GB per million mailpieces probably in a high-speed SAN with mirrored RAID 0+1

Setting Up Your Databases

MAIL360 Data Manager uses these databases

Table 1 MAIL360 Data Manager Databases

Database Suggested Name Description

Data Manager mail360dm This is the Data Manager database It includes all mailpiece information and supports all Data Manager functionality

Client Bus mail360_clientbus Contains messaging information pertaining to system messages that are passed between the MAIL360 Hub and the MAIL360 Data Manager system as well as messages passed among components of MAIL360 Data Manager

The scripts to create these databases are contained in the setup folder both on the installation media and in the file tree created by the application installer The database scripts must be run under a sysadmin-privileged login using either Windows authentication or SQL Server authentication (for example ldquosardquo)

bull To run the scripts using Windows authentication the SQL Server service must be logging into Windows as a domain (not local) user or as the Local System account

bull If desired run the scripts under a login with a sysadmin role that lasts only for the duration of the installation

Version 210June 2010 10

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 13: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Partitioning Your Data Manager Database 2

NOTE If your server has a case-sensitive collation note that the Data Manager must be created with a case-insensitive collation (This is optional for the Client Bus database) For example

CREATE DATABASE mail360dm COLLATE Latin1_General_CI_AS

Partitioning Your Data Manager Database

MAIL360 Data Manager partitions many tables by job_mailing_date It may not be necessary for you to become involved in partitioning decisions but on the other hand you do have the option of customizing the partitioning This section describes automatic partitioning and how you can customize it

Partition Function

The partition function is named partitionfunction_job_mailing_date It specifies datetime values and is range right

NOTE The MAIL360 Data Manager system ignores the initial partition which is unbounded on the left and the final partition which is unbounded on the right

You have the option of pre-creating the partition function before running the Data Manager database objects install If you do not pre-create it the install will automatically create a partition of three weeksrsquo duration through the Saturday that ends the install week

For example if the install is run on Monday January 5 2009 then the install would issue the following statement

create partition function partitionfunction_job_mailing_date

(datetime) as range right for values (2008-12-21T0000002009-01-

11T000000)

MAIL360 Data Managertrade Installation and Administration Guide 11

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 14: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

2 Setting Up Your MAIL360 Data Manager Databases

NOTE If you will be creating any jobs with mailing dates earlier than two weeks prior to the install date you should pre-create partitions before running the install

During regular Data Manager processing whenever a job is inserted with a job mailing date for which there is not already a partition the Data Manager system will check whether automatically creating a partition to include that date would be reasonable and if so will automatically create a new partition having the same duration as the last partition A partition is automatically created if the new job mailing date will fit in a new partition immediately after the last partition or (if it would not fit in that partition) in a new partition that begins on the date that the job is entered

Continuing the above example (which automatically installed a three-week partition from December 21 until January 11) if a job is now entered with a job mailing date of January 13 2009 then the Data Manager system will automatically issue the following statement

alter partition function partitionfunction_job_mailing_date()

split range (2009-02-01T000000)

to create a three-week partition from January 11 until February 1

On the other hand say that you had instead predefined a partition function with partitions of a two-week duration until January 11 Then when the new job is entered with a job mailing date of January 13 2009 the Data Manager system will automatically create the new partition with only a two-week duration from January 11 until January 25

Just as you can pre-create partitions before running the install you can explicitly create partitions afterwards to prevent or influence automatic partition growth in your Data Manager database That is you can prevent automatic partition growth by occasionally adding partitions yourself You can influence automatic partition growth by changing the duration of the last partition because new partitions that are automatically created use the duration of the last partition

Partition Scheme (File Groups)

The partition scheme is partitionscheme_job_mailing_date

Version 210June 2010 12

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 15: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Running the Scripts for the Data Manager Database 2

If you do not pre-create it before the install the install automatically creates the partition scheme using the [PRIMARY] file group for all partitions Pre-define it if you wish to place partitions in one or more other file group(s) (If you wish to place different partitioned objects in different partition schemes manually revise the database install scripts)

When Data Manager automatically adds new partitions it first checks to see whether the partition scheme(s) has already provided a file group for the new partition If not it automatically executes alter partition next used specifying the same file group as was used by the last partition

Running the Scripts for the Data Manager Database

Before executing the database setup scripts you can create an empty database that will be populated by the setup scripts This will be the case if for example you choose to pre-create a different partition function (as described above) If you do not create the database manually the create-databasebat script will create it for you

NOTE If you create the database manually be sure that the MAIL360 Data Manager database is created with a case-insensitive collation

To run the scripts to set up the MAIL360 Data Manager database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbDataManager For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1Mail360 Data Manager Web ServicessetupdbDataManager

2 Execute the batch file lsquocreate-databasebatrsquo specifying the name of your SQL Server as the first argument the name of the Data Manager database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter

If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter

If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted

MAIL360 Data Managertrade Installation and Administration Guide 13

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 16: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

2 Setting Up Your MAIL360 Data Manager Databases

EXAMPLE

create-databasebat localhostinstance2 mail360dm domain1mail360

Running the Scripts for the Client Bus Database

Before executing the Client Bus database setup scripts you can create an empty database that will be populated by the setup scripts If you do not create the database manually the create-databasebat script will create it for you To run the scripts to set up the Client Bus database do the following

1 Open a DOS window and navigate to ltyour MAIL360 Data Manager target install directorygtsetupdbClientBus For example if you installed MAIL360 Data Manager in CProgram FilesGroup 1MAIL360 Data Manager Web Services you would navigate to CProgram FilesGroup 1MAIL360 Data Manager Web ServicessetupdbClientBus

2 Execute the batch file create-databasebat specifying the name of your SQL Server as the first argument the name of the Client Bus database as the second argument and the Windows account under which the MAIL360 services log into Windows as the third parameter If you are running the install scripts under SQL Server authentication specify a sysadmin login (for example ldquosardquo) as the fourth parameter and its password as the fifth parameter (If you are using Windows authentication the Windows account running the install scripts must be a member of the sysadmin role and the fourth and fifth parameters are omitted)

FOR EXAMPLE

create-databasebat localhost mail360_clientbus sa domain1mail360

Configuring SQL Server Reporting Services (SSRS) Security

MAIL360 Data Manager uses SQL Server Reporting Services (SSRS) to generate a number of reports The SSRS Web services must be available via Windows integrated security to MAIL360 Data Managers Report Manager service This section describes how to configure SSRS for use by MAIL360 Data Manager

NOTE This configuration must be performed before the Configuration Utility is used to configure the MAIL360 Data Manager reporting facility

Version 210June 2010 14

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 17: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Configuring SQL Server Reporting Services (SSRS) Security 2

For more information see your SSRS documentation

1 Open SQL Server Management Studio specifying Reporting Services Create the new SSRS role ldquoMAIL360rdquo with the following task privileges

bull Consume Reports

bull Create Linked Reports

bull Manage Folders

bull Manage Report History

bull Manage Reports

bull View Data Sources

bull View Folders

bull View Models

bull View Reports

bull View Resources

2 Create a dedicated Windows User Account that the MAIL360 Reporting feature will use to connect to SSRS Normally the SSRS Windows service resides on a separate machine from the one hosting the MAIL360 application In this case use a domain account as this account must be available on both the MAIL360 application server and the SSRS server

3 On the machine that will host the MAIL360 Data Manager grant the Windows user you just created the right to ldquoLog on as a Servicerdquo (through Control PanelgtAdministrative ToolsgtLocal Security PolicygtLocal PoliciesgtUser Rights Assignment)

4 Create a folder within SSRS that will become the MAIL360 repository folder

5 In SSRS Report Manager set the item-level security for the folder created in Step 4 to grant the ldquoMAIL360rdquo role created in Step 1 access to the Windows user from Step 2

a First proceed to the SSRS Report Manager URL mdash typically httpltssrs service host namegtreports or for a SQL Server 2008 named instance httpltltssrs service host namegt8080reports_namedinstance For example use httphost1reports or httphost18080 reports_instance2

b Navigate through the folder structure and create a ldquoNew Folderrdquo that will become the repository folder

c Click on the folders link to enter the folder and then click the Properties tab

d Select Security on the left navigation menu SSRS will display the users that currently have access to this folder and their corresponding roles Observe

MAIL360 Data Managertrade Installation and Administration Guide 15

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 18: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

2 Setting Up Your MAIL360 Data Manager Databases

that by default an item in SSRS inherits its security configuration from the folder that contains it

e Click Edit Item Security and then New Role Assignment

6 Select the newly-created role (ldquoMail360rdquo) and enter the user name for the Windows account created in Step 2 Press OK

You will return to the main Security screen for the repository folder and you should see that your Windows User now has the Mail360 role for this folder Furthermore due to the security inheritance behavior previously-mentioned any other items (other folders reports data sources etc) added to this folder will likewise automatically allow access as the role Mail360 by this Windows User

Version 210June 2010 16

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 19: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

C H A P T E R 3

Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements 20 Installing MAIL360 Data Manager 20 What Was Done by the Install Process 25 Configuring Your Data Manager Hub Subscription 27

Entering Your Subscriber ID 28 Importing and Configuring Your Unique Identity Certificate 28 Importing the Hub Identity Certificate 30

Uninstalling MAIL360 Data Manager 30 Uninstalling via the Uninstall Wizard 30 Uninstalling via Your Control Panel 31

MAIL360 Data Managertrade Installation and Administration Guide 17

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 20: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

3 Installing the MAIL360 Data ManagerTM Web Services

Minimum Hardware Requirements

The following are the minimum hardware requirements for MAIL360 Data Manager Web services

bull Dual Core 22 Ghz +

bull 4 GB RAM

bull 50 GB of free disk space

Installing MAIL360 Data Manager

1 Locate your MAIL360 Data Manager installation file (setupexe) and double-click The MAIL360 IntallShield Wizard will appear

2 If you do not have NET Framework 35 SP1 installed you will be prompted to install it before proceeding You may have to reboot your system following this installation Once you have done this you will be able to restart and resume your Data Manager installation

3 Read and accept the license agreement Click Next

4 The Select Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Services) location then you can change the path of MAIL360 Data Manager by clicking the Change button

Click Next to display the Log File Folder screen will appear

If you do not wish to accept the default (CGroup 1 DataMAIL360 Data Managerlogs) location then you can change the path of logs files by clicking the Change button

Version 210June 2010 18

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 21: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Installing MAIL360 Data Manager 3

You will see the Service Account Settings dialog box

5 Define

bull Account Name The login name that the MAIL360 services will use to run as a services process

bull Password The password for the login name that the MAIL360 will use to run as a service process

MAIL360 Data Managertrade Installation and Administration Guide 19

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 22: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

3 Installing the MAIL360 Data ManagerTM Web Services

6 Click Next to display the Database Configuration dialog box

7 Enter the name of the SQL Server that hosts the MAIL360 Data Manager database

8 As the MAIL360 Data Manager database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

9 Enter the name of the SQL Server that will host your Client Bus database (Format will be the same as described in Step 6)

10 As the Client Bus database Catalog name enter the corresponding database name selected by the DBA as described under ldquoInstalling MAIL360 Data Managerrdquo on page 18

Version 210June 2010 20

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 23: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Installing MAIL360 Data Manager 3

11 Click Next to display the Additional Configuration for Data Manager dialog box

bull Access keys Enter your access keys (for temporary licensing) separated by commas

bull Service host name Enter the name of the host machine for your Data Manager Web services This is the machine on which you are installing the Data Manager system The example above currently shows localhost as the service host name but this could also be similar to ldquohttprdquo or ldquohttpsrdquo and mail360dmhostcompanycommail360dm

bull Data manager port Enter the TCP port on which the Data Manager system will provide Web services The default is port 8884

bull Report Manager port Enter the TCP port on which the Report Manager system will provide web services The default port is 8886

bull Identity Server port Enter the TCP port on which the Identity Server system will provide web services The default port is 8887

bull Data Manager subscriber ID Enter your Data Manager subscriber ID that was provided by Group 1 Software

bull TEMP file directory This indicates the directory where temporary files will be stored locally If you wish to change this directory click Change

MAIL360 Data Managertrade Installation and Administration Guide 21

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 24: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

3 Installing the MAIL360 Data ManagerTM Web Services

12 Click Next to display the Additional Configuration for Job Submission dialog box

13 Define your settings

bull Scanning interval The interval (in minutes) between checks for new uploaded files from the FTP input directory

bull Jobs Input File Directory The directory into which incoming files are archived When the FTP Agent processes files it removes the files from the input directory and archives them in the archive directory

bull Jobs Hot Folder The directory where the previously configured IIS FTP service stores incoming job files The FTP Agent will search this directory for new files

bull Maildat Input Directory The directory containing the maildat files

Version 210June 2010 22

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 25: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Installing MAIL360 Data Manager 3

14 Click Next when you are ready to display the Additional Configuration for Message Receiver dialog box

15 Define the settings for the Message Receiver service that processes messages and incoming files

NOTE The Notification Settings are only displayed if e-mail notification is enabled

bull Enable mail notification If this is checked the Data Manager system will send e-mail notices when mailpiece files are processed

bull Sender e-mail address The e-mail address of the account from which you wish to send the notification

bull Subscriber e-mail address The e-mail address of the recipient of the notification

bull Mail server host The host name of the SMTP mail server

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

MAIL360 Data Managertrade Installation and Administration Guide 23

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 26: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

3 Installing the MAIL360 Data ManagerTM Web Services

bull Email account password The password for the account used for sending the notification

16 Click Next to display the Additional Configuration for Client Bus dialog box

17 Enter the settings for the Client Bus service that links the Data Manager installation with the Group 1 Hub

bull Repository Path The Client Bus logs and archives incoming and outgoing messages Select the local directory where the messages will be archived

bull Bridge Check Service URI Enter the URI provided by Group 1 Software for accessing the hub It should be in the following format

httpltservergtltportgt[path]

18 Click Next to display the Permission Setting Confirmation dialog box This reminds you that permissions on queues created by the installer must be manually configured before running the Data Manager system

19 Click Next to display the Ready to Install the Program dialog box Click the Install button

The installer will now install the Data Manager components according to your configurations

NOTE As the installation proceeds you may notice a command window flash up and disappear again This is normal and indicates the execution of scripts that are configuring permissions on folders and queues

20 Click Finish to exit the installer

Version 210June 2010 24

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 27: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

What Was Done by the Install Process 3

What Was Done by the Install Process

The following actions were performed by the installer

bull The software executable programs were installed on the machine Configuration settings for each executable were stored in the installation directory

bull Windows services were created for the executable programs MAIL360 Data Manager MAIL360 FTP Agent MAIL360 Message Receiver MAIL360 Client Bus MAIL360 Report Manager MAIL360 Identity Server and MAIL360 Scheduler The services were not started you will have to start them manually

bull The Mail Identity Server handles user identification and management including

ndash Authentication and Authorization

ndash Organization Management

ndash Business role management

ndash Group Management (Associating business roles and users to a group)

ndash User Management

bull The following queues were created for use by the Data Manager system

ndash ldquoprivate$mail360-datamanager-inputrdquo

ndash ldquoprivate$mail360-datamanager-input-errorrdquo

ndash ldquoprivate$mail360-ftpagent-inputrdquo

ndash ldquoprivate$mail360-ftpagent-input-errorrdquo

ndash ldquoprivate$mail360-messagereceiver-inputrdquo

ndash ldquoprivate$mail360-messagereceiver-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-inputrdquo

ndash ldquoprivate$mail360-clientbus-input-errorrdquo

ndash ldquoprivate$mail360-clientbus-unroutablerdquo

ndash ldquoprivate$mail360-clientbus-bridge-intreceiverdquo

ndash ldquoprivate$mail360-clientbus-bridge-sendrdquo

ndash ldquoprivate$mail360-messagereceiver-inputfilesrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-inputrdquo

ndash ldquoprivate$mail360-hubmaileridnotifier-input-errorrdquo

bull Windows Workflow Foundation Services was configured to allow use of the Web services See msdnmicrosoftcomen-uslibrarybb924408aspx for more information

bull The URL for the Web services (based on the host and port specified during installation) was added to the Windows URLACL store

bull Local user groups were created MAIL360ClientBusRunAsUser MAIL360DataManagerRunAsUser MAIL360FtpAgentRunAsUser MAIL360MessageReceiverRunAsUser MAIL360IdentityServerRunAsUser MAIL360ReportManagerRunAsUser MAIL360IdentityServerRunAsUser and

MAIL360 Data Managertrade Installation and Administration Guide 25

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 28: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

3 Installing the MAIL360 Data ManagerTM Web Services

MAIL360SchedulerRunAsUser These groups contain the user accounts under which the MAIL360 software should be allowed to run as they are associated with all necessary queue and file system permissions

bull Setup scripts were stored under ltinstall directorygtsetup They can be used to re-create the databases or queues if they are removed for some reason

bull The installer placed the report definitions in the Reports folder

bull The Configuration Utility can be found under Start gt Programs gt Group 1 Software gt MAIL360 Data Manager gt Data Manager Configuration Utility This can be used to access the Report Manager and Scheduler configuration settings

Configuring Your Data Manager Hub Subscription

As part of your MAIL360 Data Manager installation package Pitney Bowes Group 1 Software will issue the following subscriber information

bull A Subscriber ID which is a string that will be entered into your application configuration (see below) You are only required to enter this if you did not do so during the Data Manager installation process via the Additional Configuration for Data Manager dialog

bull A unique installation identity certificate which will be used to identify this specific installation of MAIL360 Data Manager and to secure communication with the MAIL360 Hub

bull A Hub identity certificate which will be used to verify the identity of the Hub to your Data Manager installation

NOTE This information should be used for only a single Data Manager installation at a time using it in multiple Data Manager instances may lead to data corruption If you wish to make multiple installations of the Data Manager system contact Group 1 Support for assistance at 800-367-6950

Entering Your Subscriber ID

If you did not enter your subscriber ID during the Data Manager installation you will need to modify the property ldquodmSubscriberIdrdquo within the configuration file DataManagerconfigxml (using a text editor such as Notepad) as shown

ltadd key=dmSubscriberId value=cust_03gt

Version 210June 2010 26

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 29: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Configuring Your Data Manager Hub Subscription 3

Importing and Configuring Your Unique Identity Certificate

Your unique identity certificate will be provided as a PFX file and can be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 First open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage This will produce a tree view of all the certificates installed on the Local Machine that will be available to the MAIL360 processes

NOTE Ensure that you do not already have a certificate installed If you do please contact Group 1 Support for assistance at 800-367-6950

2 On the tree view right-click the Personal node and select All Tasks-gtImporthellip

3 When prompted browse to the PFX file provided to you

MAIL360 Data Managertrade Installation and Administration Guide 27

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 30: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

3 Installing the MAIL360 Data ManagerTM Web Services

4 When you click Next you will be prompted for a password Enter the password Group 1 Software has provided

5 Select Mark this key as exportable

6 Verify that the Certificate Import Wizard will place the certificate in the ldquoPersonalrdquo store Press Next

7 Press Finish to complete the import of your personal identity certificate

8 Next you must run the InstallHelper application that came with your MAIL360 Data Manager distribution to make the unique identity certificate accessible to the Data Manager processes To do this open a DOS command prompt and proceed to the folder where the Data Manager system has been installed

9 Change to the sub-folder InstallHelper then execute the following command line (as an Administrator)

Installhelper certificate set-permissions My ldquoPBBI CI Bridge Clientrdquo Subject MAIL360ClientBusRunAsUser R

Importing the Hub Identity Certificate

The Hub identity certificate will be provided as a CER file and can also be imported using the ldquoCertificatesrdquo snap-in of the Microsoft Management Console

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted People node and select TasksgtImporthellip

3 When prompted browse to the CER file provided to you

4 After hitting Next verify that the Certificate will be placed in the ldquoTrusted Peoplerdquo store Click Next

5 Click Finish to complete the certificate import

Congratulations Your subscription setup is now complete You can now Start (or Restart) the MAIL360 Client Bus Windows service Check the application logs for errors that indicate that the Client Bus is (1) unable to connect to the Server Bus or (2) unable to establish a secure connection to the Server Bus

Version 210June 2010 28

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 31: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Uninstalling MAIL360 Data Manager 3

Importing the Hub Certificate Authorities

Pitney Bowes Business Insight will provide you with two more CER files that represent the certificate authorities (CA) used to digitally endorse your MAIL360 Data Manager installationrsquos personal identity certificate These certificate authorities must be present in order for your MAIL360 Data Manager to successfully authenticate to the MAIL360 Hub when the Data Manager downloads data

To import these certificate authorities

1 As with the personal identity certificate open the Management Console and add the ldquoCertificatesrdquo snap-in specifying ldquoComputer accountrdquo and ldquoLocal Computerrdquo as the locations to manage

2 On the tree view right-click the Trusted Root Certification Authorities node and select TasksgtImporthellip

3 When prompted browse to the CER file whose name contains the text ldquoRoot CArdquo

4 After clicking Next verify that the certificate will be placed in the ldquoTrusted Root Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

5 On the tree view right-click the Intermediate Certification Authorities node and select TasksgtImporthellip

6 When prompted browse to the CER file whose name contains the text ldquoBridge Client CArdquo

7 After clicking Next verify that the certificate will be placed in the ldquoIntermediate Certification Authoritiesrdquo store Click Next then Finish to complete the certificate import

Uninstalling MAIL360 Data Manager

You can uninstall MAIL360 Data Manager either by using the uninstall wizard or through your Control Panel

Uninstalling via the Uninstall Wizard

The uninstall wizard is available when you launch the setup after the product has already been installed Follow the instructions in the wizard to remove the product from your system

MAIL360 Data Managertrade Installation and Administration Guide 29

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 32: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

3 Installing the MAIL360 Data ManagerTM Web Services

Uninstalling via Your Control Panel

To uninstall MAIL360 Data Manager navigate to Programs and Features in the Control Panel Scroll down to select MAIL360 Data Manager web Services and click Remove

1 Delete your logs in the Group 1 Data file

2 Reboot your system to complete the un-install process

Version 210June 2010 30

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 33: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

C H A P T E R 4

Installing the Data Manager User Interface (UI)

System Requirements 34 Installing the Web UI Software 34 Uninstalling the MAIL360 Data Manager UI 36

MAIL360 Data Managertrade Installation and Administration Guide 31

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 34: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

4 Installing the Data Manager User Interface (UI)

System Requirements

The following are required in order to run MAIL360 Data Manager UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 UI product software

1 For media installs insert the product CD into your drive Click Start and select Run In the Open field type the drive letter for your CD drive followed by the setup command For example if your CD drive is D type

dsetupexe

where d represents the D drive Click OK

For internet installs navigate to the folder where you extracted the installation zip file and double-click the setupexe file

2 The Setup Wizard will appear Click Next

3 Review the MAIL360-specific License Agreement and then select the radio button I Agree to continue with the installation (You will not be able to proceed with the installation if I Do Not Agree remains selected) Click Next

4 The Installation Folder dialog box will appear If you do not wish to accept the default (CProgram FilesGroup1Mail360 Data Manager Web Client) browse to the location using the Changehellip button

Version 210June 2010 32

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 35: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Installing the Web UI Software 4

5 Click Next The Data Manager Server Information screen will appear You will need to enter the Data Manager server name and port values The default Data Manager port is 8884

NOTE The port number should be greater than zero and less than 65536

Click Next

6 The Report Manager Server Configuration screen will appear You will need to enter the Report Manager server name and port values The default Report Manager port is 8886

Click Next

7 The Identity Server Configuration screen will appear You must define the Identity Server name and port values The default Identity Server port is 8887

8 Click Next to display the Email Settings screen If you wish to be able to send reports by email you must enter your email settings This includes the following

bull Mail server host The host name of the SMTP mail server

MAIL360 Data Managertrade Installation and Administration Guide 33

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 36: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

4 Installing the Data Manager User Interface (UI)

bull Mail server port The port on which the SMTP mail server listens

bull Email account username The name (login) of the account used for sending the notification

bull Email account password The password for the account used for sending the notification

NOTE Currently the email server information is not being validated

NOTE After installation you can edit the name port values and email information by changing these values in the config file The default location for the config file is CProgram FilesGroup1Mail360 DataManager Web Client Mail360DataManagerUIconfigxml

9 The Ready to Install screen will appear Click on Install The installation will begin at this point This process may take several moments

10 When the installation is complete the InstallShield Wizard Completed screen appears Click Finish

If Microsoft Internet Explorer is installed then the installer will automatically open the Web application in Internet Explorer at this point

The URL that you will use to access the Web application is httpserver-name datamanagerwebdefaultaspx Here ldquoserver-namerdquo will be the name of the server on which the Web Client is hosted

Uninstalling the MAIL360 Data Manager UI

To uninstall the MAIL360 Data Manager UI navigate to Add or Remove Programs in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Remove

On Windows 2008 to uninstall the MAIL360 Data Manager UI navigate to Programs and Features in your Control Panel Scroll down to select MAIL360 Data Manager Web Client and click Uninstall

You can also uninstall the UI via the uninstall wizard which is available when you launch the setup once the product has already been installed Follow the instructions in the wizard to remove the product from your system

1 The Welcome screen for the wizard appears Click Next

2 The Program Maintenance screen appears Select the Remove option and click Next

Version 210June 2010 34

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 37: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Uninstalling the MAIL360 Data Manager UI 4

3 The Remove the Program screen appears Click Remove This process may take several moments

4 When the installation is complete the Completed screen appears Click Finish

MAIL360 Data Managertrade Installation and Administration Guide 35

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 38: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

4 Installing the Data Manager User Interface (UI)

Version 210June 2010 36

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 39: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

C H A P T E R 5

Configuring MAIL360 Data Manager Configuring the MAIL360 Report Manager and Scheduler 38

Configuring the MAIL360 Report Manager 38 Service Host Settings 39 Reporting Database Setup 40 SSRS Setup 44 Report Deployment 45 Service Status 47

Configuring the Scheduler 48 Service Status 49 Scheduled Tasks 50

Additional Data Manager Configuration Options 50 Setting Permissions for MAIL360 Data Manager 51 Setting the Logging Level 51 Applying AccessLicense Keys 48

Obtain License Keys 48 Install License Keys 49 Configure the License Keys 49

MAIL360 Data Managertrade Installation and Administration Guide 37

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 40: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

5 Configuring MAIL360 Data Manager

Configuring the MAIL360 Report Manager and Scheduler

The Configuration Utility allows you to change the default settings for the MAIL360 Report Manager and Scheduler applications This utility appears under Start gt Programs gt Group 1 Software gt Data Manager Configuration Utility

The Configuration Utility has a tab for each configurable MAIL360 Data Manager component You can navigate through the components using the panel on the left-hand side of the screen Clicking a link in this panel will display the related settings on the right-hand side of the screen

Configuring the MAIL360 Report Manager

The Reports tab of the Configuration Utility allows you to set the following options (each of which is available on the left side of the screen)

bull Service Status

bull SSRS Setup

bull Report Deployment

NOTE To make these changes effective you must restart the MAIL360 Report Manager service

Version 210June 2010 38

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 41: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Configuring the MAIL360 Report Manager and Scheduler 5

Service Status

Clicking this button displays the Service Status panel which allows you to view start stop or restart the MAIL360 Report Manager service

Figure 1 MAIL360 Report Server mdash Service Status

Once displayed the screen checks for the status of the MAIL360 Report Manager service process and enables or disables command buttons based on the services current state

bull Start This is enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop This is enabled only when service status is Running Clicking this button will attempt to stop this service process

MAIL360 Data Managertrade Installation and Administration Guide 39

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 42: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

5 Configuring MAIL360 Data Manager

bull Restart This is enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility program displays the status ldquoService is unavailable or is not configuredrdquo with all the command buttons disabled

SSRS Setup

Clicking this button displays the SSRS Setup panel

Figure 2 SQL Server Reporting Services (SSRS) Connection

This allows you to configure the host port and virtual directory where MAIL360 Data Manager will access the web services exposed by SQL Server Reporting Services The fields on this panel are as follows

Version 210June 2010 40

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 43: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS host This is the URL scheme (http or https) and host name that the SSRS Web service uses to listen for client connections

bull Port This is the port number that the SSRS web service will use to listen for client connections

bull Virtual Directory This is the virtual directory path that the SSRS uses

bull Repository Folder This is the folder that serves as the MAIL360 reporting repository You can enter or browse to the repository If you choose to browse to the location you will also have the option to create a new folder

bull MAIL360 Report Object Deployment Table This table lists the status of MAIL360 reporting objects within the selected repository

bull Refresh Clicking the Refresh button will update the MAIL360 report object deployment table based on the Repository Folder field

Click Apply to confirm any changes and trigger the Task Status panel

Report Deployment

Clicking this button displays the Report Deployment panel which allows you to deploy or remove MAIL360 Data Manager reports As part of collecting report deployment information from MAIL360 the configuration utility will prompt you to log in

MAIL360 Data Managertrade Installation and Administration Guide 41

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 44: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

5 Configuring MAIL360 Data Manager

At the login prompt enter the credentials of a user who has the ReportManager role at the Root organization level (only a user with these access rights will be able to deploy reports into MAIL360)

Figure 3 Report Deployment

This screen includes a table with the following fields

bull Deployed column Click the check box to deploy or un-deploy the report on that line A check mark means that the report will be deployed when the Apply button is clicked If not checked the report will be un-deployed when the Apply button is clicked

bull Report Name column The name of the MAIL360 report

bull MAIL360 column This column shows the deployment status of the report in the MAIL360 Report Manager A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Version 210June 2010 42

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 45: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Configuring the MAIL360 Report Manager and Scheduler 5

bull SSRS column This column shows the deployment status of the report in the SSRS A value of yes means the report is currently deployed A value of no indicates that it is not deployed A value of na means the report is not applicable

Clicking on the Apply button will display the Task Status panel and for each report under MAIL360 that has been chosen to be deployed or removed for either MAIL360 or SSRS

bull Deploying Report ldquoReport Namerdquo mdash The report has been chosen to be deployed and so the Configuration Utility will attempt to deploy the report in the target system

bull Removing Report ldquoReport Namerdquo mdash The report has been chosen to be un-deployed and so the Configuration Utility will attempt to remove the report from the target system

Configuring the Scheduler

MAIL360 Data Manager uses a program called the Scheduler to set a daily time for the Hub to be notified of any mailer ID updates and for the Address Quality Dashboard database to aggregate its data The times for these operations can be set in two ways through the Configuration Utility or by updating the following keys in DataManagerconfigxml

bull HubMailerIdNotifierDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Hub should be notified It is set to 01 by default

bull HubMailerIdNotifierDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Hub should be notified It is set to 00 by default

bull AqDashboardAggregatorDailyRunHour mdash The value should be a two digit number indicating the hour (based on 24-hour notation or military time) at which the Address Quality Dashboard data should be aggregated It is set to 01 by default

bull AqDashboardAggregatorDailyRunMinute mdash The value should be a two digit number indicating the minutes after the specified hour at which the Address Quality Dashboard data should be aggregated It is set to 00 by default

MAIL360 Data Managertrade Installation and Administration Guide 43

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 46: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

5 Configuring MAIL360 Data Manager

Under the Configuration Utility you must select the Scheduler tab The Scheduler tab offers two options

bull Service Status

bull Scheduled Tasks

Service Status

Clicking this navigation button on the Scheduler tab allows you to access the Service Status panel Once displayed the screen checks for the status of the MAIL360 Scheduler service process and enables or disables command buttons based on the services current state

From here you can choose to start stop or restart the Scheduler

bull Start mdash Enabled only when service status is Stopped Clicking this button will attempt to start this service process

bull Stop mdash Enabled only when service status is Running Clicking this button will attempt to stop the service process

bull Restart mdash Enabled only when service status is Running Clicking this button will attempt to stop and then restart this service process

NOTE If the service process is unavailable or not properly configured the Configuration Utility displays the status ldquoService is unavailable or not configuredrdquo with all the command buttons disabled

Version 210June 2010 44

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 47: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Additional Data Manager Configuration Options 5

Scheduled Tasks

Clicking this button displays the Scheduled Tasks panel which allows you to set the daily time at which certain Data Manager components should run

You can enter or click to the desired hour minute and AMPM indicator to specify when the Hub Mailer ID Notifier and the Dashboard Report Aggregator should be run each day Changing any of the time parameters will enable the Apply button at the bottom of the screen Clicking Apply will update the scheduled times You can confirm the success of the update by looking at the Task Status panel that will appear at the bottom of the screen

Additional Data Manager Configuration Options

The options configured during installation are accessible through your Data Manager configuration files These are located in your main program installation folder They are as follows

bull ClientBusconfigxml mdash Allows you to update database user identification information and the frequency with which the Client Bus communicates with Hub

bull DataManagerconfigxml mdash Allows you to update the following

ndash Your access keys and licensing information

ndash Data Manager Report Manager and Identity Server host name and ports

ndash Data Manager Report Manager amp Identity Server host name and ports

ndash TEMP file directory

ndash Identity Server settings

ndash SSRS settings for Report Manager

ndash The userrsquos Data Manager subscriber ID

ndash Event notification e-mail information

ndash Temp and archive directories

ndash Database connection string for the Data Manager

ndash Path of the key file storage location

bull Log4netconfig mdash Allows you to set the level of detail that is logged for requests and responses (SeeldquoSetting the Logging Levelrdquo on page 47) Each component has its own log4netconfig file as follows

ndash Data Manager DataManagerlog4netconfig

ndash Client Bus ClientBuslog4netconfig

ndash FTP Agent FtpAgentlog4netconfig

ndash Message Receiver MessageReceiverlog4netconfig

ndash Report Manager ReportManagerlog4netconfig

MAIL360 Data Managertrade Installation and Administration Guide 45

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 48: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

5 Configuring MAIL360 Data Manager

ndash Scheduler Schedulerlog4netconfig

ndash Identity Server IdentityServerlog4netconfig

ndash DM Config DMConfiglog4netconfig

The installer will install log4net files for the following additional components that are internal to the system

ndash DbAggregator DbAggregator

ndash HubMailerIdNotifier HubMailerIdNotifierlog4net

ndash IdentityProvidersxml Allows you to set the LDAP settings

ndash InputFileSourcesxml Allows you to change path of the job input directory and maildat directory

MAIL360 Data Manager also includes a utility called InstallHelper that allows you to define privileges for the URL resource

Setting Permissions for MAIL360 Data Manager

This section covers permissions for the Data Manager Report Manager and Identity Server applications

The MAIL360 Data Manager installation configures permission for the DataManager application to run a Web service using the following command

InstallHelperexe url-acl set-permissions https +portmail360 D(AGXS-groupID)

For more where port is the port number selected during the installation process information on D(AGXS-group) is Windows SDDL (Security Descriptor Definition Windows SDDL see Language) that defines who has what privileges on a URL resource The groupID the Microsoft component will vary per host machine It is an identifier that refers to the Developers

ldquoMail360DataManagerRunAsrdquo user group which includes the built-in ldquoNetwork Network http msdnmicrosoftco Servicerdquo account as a member By controlling membership for the men-uslibrary Mail360DataManagerRunAs group you can control who has access to the MAIL360 aa379567(VS85)as Data Manager Web services px

The following sets up permission for a group with an ID of ldquo1-5-21-516131862-4152794910-1508380200-1046rdquo (on port 8884)

InstallHelperexe url-acl set-permissions https+8884mail360 D(AGXS-1-5-21-516131862-4152794910-1508380200-1046)

Version 210June 2010 46

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 49: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Setting the Logging Level 5

Setting the Logging Level

Request and response information for MAIL360 Data Manager is logged to the ServiceInvocation log You can control the level of detail recorded to that log by configuring the appropriate value in the DataManagerlog4netconfig file in the install directory

The following valueslevels are available

bull ERROR mdash Requests are not logged Responses are logged only if the HTTP response code is 500+ (internal service error) The operation name and entire message body are logged

bull WARN mdash Requests are not logged Responses are logged only if the HTTP response code is 400+ (bad request or internal service error) The operation name and entire message body are logged

bull INFO mdash For requests the operation name HTTP method (GET POST etc) and URI are logged No message headers or request body information is recorded For replies the operation name and status code are provided

bull DEBUG mdash The full request and reply information is provided

NOTE Logging levels are hierarchical each level including the information of its subordinate levels Within the Data Manager system the levels are defined by increasing severity as follows DEBUG lt INFO lt WARN lt ERROR So if you choose to record information to your log at the WARN level you will receive both WARN and ERROR messages if you choose DEBUG you will receive all messages

MAIL360 Data Managertrade Installation and Administration Guide 47

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 50: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

5 Configuring MAIL360 Data Manager

Applying AccessLicense Keys

MAIL360 Data Manager requires temporary access keys and license key files

Obtain License Keys

To obtain your permanent license key file

1 Go to the Support area of the Group 1 website at httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupport loginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Click on the ldquoMy Productsrdquo link on the left-hand navigation bar

4 Click on the name of the product for which you are downloading the permanent license key file

5 Click the ldquoView Detailrdquo link next to the platform for which you are downloading the permanent license key file

NOTE The following steps may differ depending on the number of components your Enterprise Server-based product contains

6 Scroll down to the ldquoSubComponentsrdquo section and click the ldquoView Detailrdquo link next to the component for which you are downloading the permanent license key file

7 Click the ldquoDownloadrdquo link under the ldquoLicense Filerdquo column in the ldquoProductsrdquo table A dialog box will appear asking you to save the file

8 Click [Save]

Version 210June 2010 48

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 51: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Applying AccessLicense Keys 5

Install License Keys

To Install your permanent license key

1 Go to httpwwwg1comsupport

2 Log into the Support area with your user ID and password

NOTE If you do not know your User ID and password for the Support website please go to the Login screen (httpwwwg1comsupportloginasp) and select the option to have it e-mailed to you or call Tech Support (800-367-6950) to obtain your User ID and password

You will be asked to provide your e-mail address which must be an exact match to what is in our customer database If a successful match is found your User ID and password will be e-mailed to the address entered

3 Select ldquoMy Productsrdquo from the left hand column of the Web page

4 Select the product you want to install from the list

5 Select ldquoView Detailrdquo for the platform you want to install

6 Select ldquoDownloadrdquo under ldquoLicense Filerdquo for the version of the software you want to download

7 Click Save to download your permanent license key file to the directory you specify

Configure the License Keys

You must apply your license key(s) to the MAIL360 ldquoservicerdquo components Edit the DataManagerconfigxml file as follows

1 Paste the access key into the ldquoaccessKeysrdquo value in the config file

ltadd key=accessKeys value=04-1234994321-IMD gt

2 Update the permanent license key

MAIL360 Data Managertrade Installation and Administration Guide 49

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 52: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

5 Configuring MAIL360 Data Manager

a Save the downloaded license key file to your local disk (for example in the applicationrsquos installation directory)

b Edit the DataManagerconfigxml file add the full path of the license key file to the ldquolicenseFilerdquo value ltadd key=licenseFile value=CProgram FilesGroup1Mail360DataManagerlicensekey gt

Version 210June 2010 50

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 53: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

C H A P T E R 6

Installing the MAIL360 Identity Server UI System Requirements 52 Installing the Web UI Software 52

MAIL360 Data Managertrade Installation and Administration Guide 51

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 54: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

6 Installing the MAIL360 Identity Server UI

System Requirements

The following are required in order to run MAIL360 Identity Server UI on your computer

bull Windows XP Service Pack 2 or Windows Server 2003 or Windows Server 2008

bull IIS 51 60 or 70 (to be manually installed)

bull Internet Explorer 60 or 70

bull NET Framework 35 with Service Pack 1(If you do not already have it the installer will prompt you to initiate the Web download)

bull Microsoft ASPNET MVC 10 (automatically installed by the installer if it is not on machine)

Installing the Web UI Software

Complete the steps below to extract and install the MAIL 360 Identity Server UI

1 For media installs

a Insert the product CD into your drive

b Click Start select Run

c In the Open field type the letter for your CD drive followed by the setup command For example if your CD drive is E type esetupexe

d Click OK

2 For internet installs

Version 210June 2010 52

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 55: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Installing the Web UI Software 6

a Navigate to the folder where you extracted the installation zip file and double-click the setupexe file

b Click Next when the Setup Wizard appears

3 Review the MAIL360-specific License Agreement and then select I Agree to continue with the installation

NOTE You will not be able to proceed with the installation if I Do Not Agree remains selected

MAIL360 Data Managertrade Installation and Administration Guide 53

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 56: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

6 Installing the MAIL360 Identity Server UI

4 Click Next to display the Installation Folder dialog box

5 If you do not wish to accept the default location browse to another location using the Changehellip button

6 Click Next to display the Identity Server Information screen

7 Enter the Server name and Server port values

Version 210June 2010 54

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 57: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Installing the Web UI Software 6

NOTE The default Identity Server port is 8887 The port number should be greater than zero and less than 65536

8 Click Next to display the Ready to Install screen

NOTE After installation you can edit the name port and protocolIdentityServer values by changing these values in the config file A mandatory field named clientIdentifier points to the ldquosubject namerdquo of the certificate installed and should also be provided in the config file The certificate is required by the Web UI to communicate with the Identity Server Web Service The default location for the config file is CProgram FilesGroup1Mail360IdentityServer Web Client Mail360IdentityServerUIconfigxml

9 Click Install to start the installation process This may take several minutes

10 Click Finish on the InstallShield Wizard Completed screen

After a successful installation you will see the Web application in Internet Explorer Access the Web application with the URL httpserver-name identityserveruidefaultaspx Replace ldquoserver-namerdquo with the name of the server hosting the Web Client

MAIL360 Data Managertrade Installation and Administration Guide 55

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 58: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

6 Installing the MAIL360 Identity Server UI

Version 210June 2010 56

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 59: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

C H A P T E R 7

MAIL360 Data Manager Security MAIL360 Security 58 Configuring the clientIdentifier 58 Organizations Groups and Roles 59 Authentication 60

User Name and Password Profile 60 Windows Authentication Profile 61 User Name and Password with Restricted Access Profile 62

Computing the Client Signature 63 Invoking MAIL360 Web Services with the Access Token 63

MAIL360 Data Managertrade Installation and Administration Guide 57

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 60: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

7 MAIL360 Data Manager Security

MAIL360 Security

Some aspects of the MAIL360 security architecture are interconnected particularly authentication and authorization User identity is central to the MAIL360 security model According to MAIL360 a user has the following elements

bull E-mail address

bull Full name that can be parsed into components

ndash First name

ndash Last name

bull Parent organization

bull [Security] Group memberships

bull An active account

bull Password conforming to MAIL360 guidelines

User identities within MAIL360 originate from two sources

bull Users created within MAIL360 and stored in the MAIL360 database (these are the ldquoMAIL360-specific user accountsrdquo)

bull Zero or more Windows Active Directory servers that a system administrator has integrated with MAIL360

The active directory support allows MAIL360 authentication through Windows credentials Regardless of the source of a userrsquos account an administrator must still grant access rights in order for the user to perform operations with MAIL360 Administrators assign these access rights within MAIL360 through the UI

Configuring the clientIdentifier

MAIL360 Data Manager Web services require that applications acting on behalf of other principals use a client identity (in the form of an X509 certificate) to sign their requests for access tokens We recommend that you use the Data Manager UIs SSL certificate as the client identity Once you have configured Data Manager for HTTPS the SSL certificate resides in the LocalMachinePersonal store

1 Copy the certificate (the public key portion) into the LocalMachine TrustedPeople store

2 Open the certificate and determine the Subject name

3 Open the Mail360DataManagerUIconfigxml file (from the UI install directory) in a text editor

4 Enter the Subject name as the ldquoclientIdentifierrdquo value and save the file

Version 210June 2010 58

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 61: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Organizations Groups and Roles 7

Organizations Groups and Roles

MAIL360 relies on organizational ownership of data to determine a users access rights MAIL360 Identity Server uses a RootParentChild structure to manage user accounts groups roles and permissions

bull Organizations ndash Break business entities into subsidiaries divisions or departments

bull Hierarchies ndash Represent organizational structures within the system as hierarchies for example ldquoWest Coast Divisionrdquo and ldquoCentral Divisionrdquo

bull Data objects (jobs reports mailpieces user accounts business role definitions and so on) ndash Link to their respective ldquoownerrdquo organizations

bull Group memberships ndash Provide the means by which a MAIL360 administrator defines permissions to access add or delete data

ndash A user can belong to multiple groups

ndash Groups serve an additional purpose for Active Directory log-ins Administrators can assign access rights to an Active Directory user account based on whether one or more of its Active Directory Group names match to names of Groups defined within the MAIL360 database For matches the Active Directory user has the same rights associated with the matched MAIL360 group

Table 1 Identity Server Application Roles (Part 1 of 2)

This Role Provides this user access

UserBrowser View user account information (excluding password) but not change it

UserManager View edit create and delete user accounts

GroupBrowser View the membership of a user group

GroupManager View or alter the membership of user groups or group access rights

OrganizationBrowser View Organizational relationships

OrganizationManager Change organizational relationships (change the hierarchical structure) or add an organization

BusinessRoleBrowser See available business roles and the application roles they contain

BusinessRoleManager View create edit and delete business roles

JobBrowser View available jobs and search those for mailpieces

JobManager Create close and add mailpieces to jobs

MailDatManager Add and delete a MailDAT tofrom MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 59

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 62: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

7 MAIL360 Data Manager Security

Table 1 Identity Server Application Roles (Part 2 of 2)

This Role Provides this user access

UploadedFileBrowser Obtain a listing of files (mailpiece files maildat files) loaded into MAIL360

UploadedFileManager

FileBrowser

ReportManager Add modify view and remove report definitions execute reports and view the output from an executed report

ReportBrowser List the report definitions available list the report executions available and view the output from an executed report

ReportExecuter List the report definitions available list the report executions available execute a report and view the output from an executed report

Authentication

To access MAIL360 services

Users must first be Authenticated by Data Managers Identity Server Identity Server supports the following authentication methods (these are based on profiles 51 and 53 of the OAuth-WRAP v972 protocol)

bull User name and password Appropriate for use by an autonomous process that invokes MAIl360 Web services under a dedicated (least-privileged) user account

bull Windows authentication Useful for processes that invoke MAIL360 web services and run under a dedicated Windows user account From a security standpoint this method is preferable to User name and Password

bull User name and password with client access restriction Appropriate for use by an application that first collects the Users credentials before passing them along to the Identity Server for authentication This authentication method incorporates a ldquoclient access restrictionrdquo to remove from the application the responsibility for protecting the end-users user name and password from theft and is therefore recommended for use by any sort of application that asks a User to log into the Data Manager web services using his own user name and password so that the application can act on the Users behalf

User Name and Password Profile

The client performs an HTTP POST to the MAIL360 Identity services to authenticate by User name and Password

Version 210June 2010 60

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 63: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Authentication 7

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded wrap_name=lturl encoded usernamegtampwrap_password=lturl encoded passwordgt

If the specified user name and password combination is valid the Identity services respond with an access token and a token expiration period

HTTP11 200 OK Content-type applicationx-www-form-urlencoded charset=utf-8

wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse out the access token from the response (dont forget to URL decode it) and store it for later use you will include it as part of subsequent request to other MAIL360 web services (described later) You may also wish to parse out the expiration period for display or logging purposes (use of the expiration period is optional and will not affect the behavior of MAIL360)

If the specified user name and password combination are invalid the Identity Services will instead respond with an Unauthorized message

HTTP11 401 Unauthorized

The Identity Services respond with an ldquounauthorizedrdquo message if an internal error occurs during authentication If the user name and password are correct check the Data Managers identity logs for possible configuration errors

Windows Authentication Profile

To authenticate using a Windows login account a client application must prepare an HTTP request that includes credentials necessary for Windows authentication (support for Windows authentication is platform-specific and is beyond the scope of this document) then execute a POST as follows

POST mail360wrapwindowsAuthaccessTokens Content-Length 0

Assuming the Windows account is valid the Identity services will respond in a manner similar to the User name and Password profile

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf8-8 wrap_access_token=lturl encoded access token valuegtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Parse and store the access token for later use as described under the user name and password profile If Windows Authentication fails the Identity Services will respond with a 401 Unauthorized message

MAIL360 Data Managertrade Installation and Administration Guide 61

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 64: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

7 MAIL360 Data Manager Security

HTTP11 401 Unauthorized Content-Length 0 WWW-Authenticate Negotiate

The Identity services will also respond with an Unauthorized message if an internal error occurs during authentication Try checking the Data Managers identity logs for possible configuration errors

User Name and Password with Restricted Access Profile

Authentication under this profile proceeds in a manner similar to the User name and password profile except that the service caller must also specify a ldquowrap_client_idrdquo parameter and should use the parameter ldquowrap_usernamerdquo in place of ldquowrap_namerdquo as shown

POST mail360wrapwrapAuthaccessTokens Content-Type applicationx-www-form-urlencoded

wrap_username=lturl encoded usernamegtampwrap_password=lturl encoded passwordgtampwrap_client_id=lturl encoded client identifiergt

The ldquoclient identifierrdquo refers to the client application itself as opposed to the end-user More specifically it identifies by Common Name a Certificate (with RSA private key) that has

bull Been installed in the Personal certificate store (Local computer) on the system that hosts the client application and

bull Has been installed without private key in the ldquoTrusted Peoplerdquo certificate store (Local computer) on the system that hosts the Data Manager web services

If the client application already uses an SSL certificate it may be convenient to reuse this certificate as a client identifier to reduce the number of certificates included in the system deployment

If the user name and password are valid the system will respond as follows

HTTP11 200 OK Content-Type applicationx-www-form-urlencoded charset=utf-8

wrap_refresh_token=lturl encoded refresh tokengtampwrap_access_token=lturl encoded access tokengtampwrap_access_token_expires_in=ltexpiration period in secondsgt

Under this profile the system responds with a ldquoRefresh tokenrdquo as well as an Access token when successful authentication occurs The refresh token represents a long-lived key to obtain a new access token in the users name but is also linked to the identity of the client application acting on the users behalf storage of the refresh token offers a more secure alternative than local storage of the users name and password

Version 210June 2010 62

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 65: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Authentication 7

When the access token eventually expires the client application may ldquorefreshrdquo the users access by requesting a new token in the following manner

POST mail360wrapwrapAuthaccessTokens Content-type applicationx-www-form-urlencoded

wrap_refresh_token=lturl encoded refresh token (exactly as provided by the server)gtampmail360_refresh_token_client_signature=lturl encoded client signature as described belowgt

Computing the Client Signature

The client application must provide a signature as part of its token refresh request in order to prove the client applications ownership of the token This signature should be calculated according to the following procedure

1 URL decode the refresh token

NOTE The refresh token should only be decoded once from the form in which it was received Additional decode actions may prevent the identity server from verifying the client signature and prevent the access token from being refreshed

2 Convert the decoded refresh token from characters into bytes according to the UTF-8 character set

3 Compute a digital signature of the bytes from (2) by first passing the bytes through a SHA1 message digest function and then encrypting the resulting message digest using the private key of the clients RSA certificate

4 Convert the digital signature from (3) into Base-64 representation

5 URL encode the signature from (4) This is the value that should be set as the ldquomail360_refresh_token_client_signaturerdquo

As with other authentication methods an unsuccessful refreshing of the access token will be met with a ldquo401 Unauthorizedrdquo response from the Identity Server The application logs may contain additional detail regarding the cause of the failure

Invoking MAIL360 Web Services with the Access Token

Once the client application receives an access token from MAIL360 Identity services the client application must include an HTTP authorization header

MAIL360 Data Managertrade Installation and Administration Guide 63

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 66: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

7 MAIL360 Data Manager Security

Authorization WRAP access_token=lturl decoded access tokengt

For example an HTTP request to create a new MAIL360 user should resemble the following

GET mail360users Authorization WRAP access_token=lthellipusers access tokenhellipgt Content-Type applicationxml

ltuser xmlns=httpwwwpbcompbbicimail360v1gt hellipuser informationhellip ltusergt

The client application may use the access token to make as many service calls as it chooses After a certain time interval however the access token will expire and the web services will respond with a ldquo401 Unauthorizedrdquo error rather than completing successfully The client application will need to obtain a new access token from the Authentication services according to one of the profiles described previously at which point the client application may resume calling the web services

When attempting to invoke a web service with a particular users access token the client application receive a ldquo403 Forbiddenrdquo message This message indicates that the user with the problem access token does not have access rights to perform the requested operation In this case an administrator must grant the appropriate MAIL360 privileges

Version 210June 2010 64

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 67: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

C H A P T E R 8

Data Manager Configuration (Config) Settings

About the Data Manager Configuration Files 66 DataManagerconfigxml 66 ClientBusconfigxml 68 InputFileSourcesxml 69 IdentityProvidersxml 69 MAIL360 Identity Provider Configuration 70 Local Windows Identity Provider Configuration 71 Active Directory Identity Provider Configuration 71

Inbound Mailpiece Record 72 Trailer Record 72

MAIL360 Data Managertrade Installation and Administration Guide 65

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 68: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

8

About the Data Manager Configuration Files

This document describes the files used to configure MAIL360 Data Manager All of the files live in the main installation directory Many of the settings are configured initially by the installer or by the DMConfig utility However you may change these settings manually

DataManagerconfigxml

DataManagerconfigxml contains keyvalue pairs for configuring the DataManager service components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance1database=mail360 dmtrusted_connection=true

dmSubscriberId The identifier for your Data Manager instance used in communicating with the Hub value is provided by PBBI Technical Support This info is provided by support along with the hub certificates as part of the setup process

licenseFile The location of your permanent license file (if any)

accessKeys Temporary access key(s) separated by commas

temporaryDirectory Temporary storage for various working files

dmServiceHostName

idServerServiceHostName

rptMgrServiceHostName

Internet DNS hostname of the application server independently configured for Data Manager Identity Server and Report Manager service components

dmServicePort The TCP port numbers for Web services

idServerServicePort

rptMgrServicePort

createJobWSCommandTimeoutSecs Configures the maximum time to run a Web request to create a job

inputFileStatusNotificationFlag Set to ldquo1rdquo to enable email notification when a job or Maildat file is processed

inputFileStatusNotificationMailFromAddress ldquofromrdquo email address for input file notification

inputFileStatusNotificationMailToAddress ldquotordquo email address for input file notification

Version 210June 2010 66

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 69: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

DataManagerconfigxml 8

Key Description

emailServerHost

emailServerPort

SMTP server hostname and port number for email notifications

emailUsername

emailPassword

Email server username and password for sending email notifications

scanInterval Interval (in minutes) for FtpAgent to poll the job submission hotfolder

jobsHotFolderInputFileSourceName The name of the entry in InputFileSourcesxml that serves as the job submission hotfolder

jobsArchiveFolder The filesystem directory where job files will be archived after they are submitted to the job submission hotfolder Files do not need to remain here and you may clear this directory as often as convenient

hubMailerIdNotifierQueryTimeoutSecs The maximum time (in seconds) for the HubMailerIdNotifiers database query to run You may increase this setting if the scheduled task time-outs during heavy processing

hubMailerIdNotifierJobMailingDateLookbackDays Looks for jobs with jobMailingDates within the specified number of days prior optimizes query performance by taking advantage of database partitioning scheme

HubMailerIdNotifierDailyRunHour

HubMailerIdNotifierDailyRunMinute

The time for the HubMailerIdNotifier process to run daily

AqDashboardAggregatorDailyRunHour

AqDashboardAggregatorDailyRunMinute

The time for the Address Quality Dashboards data aggregation process to run daily

ssrs2005VirtualDirectory The SQL Server Reporting Services (SSRS) virtual directory

ssrs2005HostName The host and port on which SSRS runs

ssrs2005Port

ssrs2005UrlScheme ldquohttprdquo or ldquohttpsrdquo indicating the mode in which SSRS web services operate

ssrsRepositoryPath The SSRS repository folder devoted to MAIL360 reports and working storage Typically ldquo mail360rdquo

clientCertificateStoreName Typically ldquoTrustedPeoplerdquo indicates where the Identity Server stores client identity certificates that identify applications to authenticate for end users

clientCertificateStoreLocation Typically ldquoLocalMachinerdquo

clientCertificateFindType Typically ldquoFindBySubjectNamerdquo

MAIL360 Data Managertrade Installation and Administration Guide 67

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 70: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

8

Key Description

clientSignatureHashAlgorithmName Typically ldquoSHA1rdquo

shouldFindValidClientCertificatesOnly Typically ldquotruerdquo ensures that client identity certificates are valid

passwordLengthMinimum MAIL360 user account (as opposed to accounts provisioned through Active Directory) password policy minimum password length

passwordLengthMaximum MAIL360 user account password policy maximum password length for MAIL360 user accounts

passwordContainNumeric MAIL360 user account password policy ldquotruerdquo forces passwords to contain a numeral

passwordContainLowercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain a lowercase letter

passwordContainUppercase MAIL360 user account password policy ldquotruerdquo forces passwords to contain an uppercase letter

passwordContainSpecialLetter MAIL360 user account password policy ldquotruerdquo forces passwords to contain one of $

accessTokenLifetimeSeconds The time (in seconds) Identity Server access tokens remain valid

keyStoreFilePath The full path for the ldquokeystorexmlrdquo file

keyStoreShouldUseMachineProtection ldquoTruerdquo uses the Windows encryption mechanism to protect the keystore data with a machine-specific key

ClientBusconfigxml

ClientBusconfigxml contains keyvalue pairs for configuring the ClientBus components

Key Description

dbConnectionString Database connection string for the main DataManager database standard ADONet connection string

Example server=machine1instance2database=mail360dmtrusted_conn ection=true

BridgeCheckServiceUri URL used to contact the MAIL360 Hub

Version 210June 2010 68

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 71: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

InputFileSourcesxml 8

Key Description

RepositoryPath Filesystem directory for storing compressed data attachments to bus messages

BridgeCycleTimeSpan Frequency with which MAIL360 Data Manager should contact the central MAIL360 Hub to collect USPS event data

Format hhmmss (eg ldquo020000rdquo for two hours)

InputFileSourcesxml

This file contains keyvalue pairs for Input File Sources used in submitting jobs and maildats You will need to fill in values for these shared directories

The ldquojobsrdquo key corresponds to the DataManagerconfigxml entry ldquojobsHotFolderInputFileSourceNamerdquo

EXAMPLE

ltobjects xmlns=httpwwwspringframeworknet xmlnsxsi=http wwww3org2001XMLSchema-instance xsischemaLocation=http wwwspringframeworknet httpwwwspringframeworknetxsdspring-objectsxsdgt ltobject id=inputFileSources type=InputFileSourceMapgt

ltconstructor-arg index=0gt ltname-valuesgt

ltadd key=jobs value=cmail360datajobs-hotfoldergt ltadd key=maildats value=maildatPCmaildatfoldergt

ltname-valuesgt ltconstructor-arggt

ltobjectgt ltobjectsgt

IdentityProvidersxml

This file allows you to configure the sources which IdentityServer can use to authenticate users The file has two sections The first section is simply a list of references to identity providers The second section is the identity provider definitions themselves The types of identity providers are MAIL360 Active Directory and Local Windows

bull MAIL360 Provides user accounts that are defined within MAIL360 These are the accounts which the Identity Servers ldquoUsersrdquo screen manipulates Users authenticate via username and password

bull Active Directory This provider integrates with an Active Directory server so that users can authenticate via username and password using the same credentials as for logging into Windows This allows you to rely on your existing Active Directory infrastructure rather than creating an additional set of application-specific user accounts for MAIL360

MAIL360 Data Managertrade Installation and Administration Guide 69

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 72: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

8

bull Local Windows Uses an operating system handshake to provide the identity of the user account under which the client is executing As with the Active Directory provider the user accounts are provided by the Windows environment (ie your Active Directory server or local Windows machine account) rather than MAIL360 However this provider does not ask for user credentials it merely reflects the identity of the already-authenticated user

You can configure one or more identity providers depending on the user account sources you wish to support For example

ltref object=mail360IdentityProvidergt ltref object=department1ActiveDirectoryIdentityProvidergt ltref object=department2ActiveDirectoryIdentityProvidergt

This configuration supports user accounts from two separate Active Directory domains as well as application-specific MAIL360 accounts (perhaps for users who do not belong to your organization)

The default IdentityProvidersxml file provided by the installer contains example templates for each type of identity provider

Each of the identity providers has a different set of configuration properties

MAIL360 Identity Provider Configuration

ProviderName ndash Unique administrator-defined name used to identify the MAIL360 provider

Version 210June 2010 70

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 73: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Local Windows Identity Provider Configuration 8

Local Windows Identity Provider Configuration

ProviderName Arbitrary unique name to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

Active Directory Identity Provider Configuration

ProviderName Administrator-defined name used to identify the provider within MAIL360

ParentOrganizationCode Identifies the organization to which a user belongs (example ldquoTenantCodeOrgCoderdquo)

StartingPath URI of the Active Directory server (example ldquoLDAP sampledomaincomrdquo)

DomainName Domain name

SecurityIdentifierAttribute Attribute containing the users security identifier (example ldquoobjectSidrdquo)

FirstNameAttribute Attribute containing the users first name (example ldquogivenNamerdquo)

LastNameAttribute Attribute containing the users last name

EmailAddressAttribute Attribute containing the users email address (example ldquomailrdquo)

UserPrincipalNameAttribute Attribute containing the users principal name (example ldquouserPrincipalNamerdquo)

GroupMembershipAttribute Attribute indicating group membership (example ldquomemberOfrdquo)

GroupNameAttribute Attribute indicating the name of a group (example ldquonamerdquo)

ShouldIncludeLocalGroups ldquotruerdquo if the users local machine groups should be included in those considered by Identity Server

MAIL360 Data Managertrade Installation and Administration Guide 71

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 74: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

8

Inbound Mailpiece Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoIrdquo Required

Imb 2 31 Required

Data1 33 64 Optional

Data2 97 64 Optional

Data3 161 64 Optional

Trailer Record

Field Type Starting Position Size Value RequiredOptional

Record Type 1 1 ldquoTrdquo Required

Total Mailpiece Sets 2 10 Required

Version 210June 2010 72

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record
Page 75: MAIL360 Data Manager v2.1.0 Installation and ... · • FTP Agent: Periodically checks a user-specified input directory for uploaded jobs to be processed by the Data Manager system

Pitney Bowes Business Insight One Global View Main +1 (301) 731-2300 Troy New York 12180 Sales +1 (888) 413-6763 wwwpbinsightcom Support +1 (800) 367-6950

  • Table of Contents
  • Preparing for Your MAIL360 Data Manager Installation
    • Welcome to the MAIL360 Data Managertrade System
    • Installation and Configuration Overview
    • System Prerequisites
    • Information You Will Need
      • Setting Up Your MAIL360 Data Manager Databases
        • Prerequisites
        • Hardware Requirements
        • Setting Up Your Databases
        • Partitioning Your Data Manager Database
          • Partition Function
          • Partition Scheme (File Groups)
            • Running the Scripts for the Data Manager Database
            • Running the Scripts for the Client Bus Database
            • Configuring SQL Server Reporting Services (SSRS) Security
              • Installing the MAIL360 Data ManagerTM Web Services
                • Minimum Hardware Requirements
                • Installing MAIL360 Data Manager
                • What Was Done by the Install Process
                • Configuring Your Data Manager Hub Subscription
                  • Entering Your Subscriber ID
                  • Importing and Configuring Your Unique Identity Certificate
                  • Importing the Hub Identity Certificate
                  • Importing the Hub Certificate Authorities
                    • Uninstalling MAIL360 Data Manager
                      • Uninstalling via the Uninstall Wizard
                      • Uninstalling via Your Control Panel
                          • Installing the Data Manager User Interface (UI)
                            • System Requirements
                            • Installing the Web UI Software
                            • Uninstalling the MAIL360 Data Manager UI
                              • Configuring MAIL360 Data Manager
                                • Configuring the MAIL360 Report Manager and Scheduler
                                  • Configuring the MAIL360 Report Manager
                                  • Configuring the Scheduler
                                    • Additional Data Manager Configuration Options
                                    • Setting Permissions for MAIL360 Data Manager
                                    • Setting the Logging Level
                                    • Applying AccessLicense Keys
                                      • Obtain License Keys
                                      • Install License Keys
                                      • Configure the License Keys
                                          • Installing the MAIL360 Identity Server UI
                                            • System Requirements
                                            • Installing the Web UI Software
                                              • MAIL360 Data Manager Security
                                                • MAIL360 Security
                                                • Configuring the clientIdentifier
                                                • Organizations Groups and Roles
                                                • Authentication
                                                  • User Name and Password Profile
                                                  • Computing the Client Signature
                                                  • Invoking MAIL360 Web Services with the Access Token
                                                      • Chapter 8
                                                        • About the Data Manager Configuration Files
                                                        • DataManagerconfigxml
                                                        • ClientBusconfigxml
                                                        • InputFileSourcesxml
                                                        • IdentityProvidersxml
                                                        • MAIL360 Identity Provider Configuration
                                                        • Local Windows Identity Provider Configuration
                                                        • Active Directory Identity Provider Configuration
                                                          • Inbound Mailpiece Record
                                                          • Trailer Record