The Inventua PassThroughTarget Module(s) for DotNetNuke are intended to be used in one of two ways:

1.  Users with a DotNetNuke 2.1.2 portal with legacy modules and configuration can implement DotNetNuke 3 gradually by implementing a new DotNetNuke 3 portal and gradually moving content and functionality to the new portal while maintaining a seamless end-user experience by using the PassThrough modules to navigate between portals.

2.  Users with two or more DotNetNuke 3 portals in a "group" who want users to be able to navigate between their portals seamlessly can use the PassThrough modules to make it appear as though end users are browsing a single website/DotNetNuke portal instance.  Users will maintain their identity across portals automatically.

The Inventua PassThrough modules for DotNetNuke sends a user from a "source" DotNetNuke page to a "target" DotNetNuke page and automatically logs them in using the user credentials from the source portal.  If a user account does not already exist in the target portal, the PassThrough module automatically creates one using the user information from the source portal.  The module can also synchronize the security roles a user belongs to between portals, if the security role names match across portals.

Installation
The installation zip files for the "source" and "target" modules are configured as DotNetNuke Private Assemblies. To install the Inventua DNN PassThroughTarget or PassThroughSource module to your DNN portal, log in as the DNN host user "host" and use the DNN Module Definitions page to upload the module (or for DNN 2.1.2, use the File Manager page from the host menu).  You should read the "special notes" section before installing. 

How it works
The PassThrough source module is placed on a page in your original "source" site.  This module is configured with the URL of a page on your target DNN portal.  When the page containing the source module is visited, the user is redirected to the target URL with data identifying the source portal user in the querystring.  When the page containing the PassThrough target module receives and successfully decrypts the user identifier, it uses this data to access the database of the source DNN portal and collect additional user information in order to create a new user in the target portal, log the user in and synchronise passwords and security roles (depending on the settings of the PassThrough target module).

You can configure multiple "target" pages in the same portal or in different portals by creating multiple pages in your source portal that contain their own instance of the PassThroughSource module with individual settings.

Compatibility
The PassThrough source module is designed to work with the PassThrough target module.  A PassThrough source module has one version for DNN version 2.1.2 and another for DNN 3 & 4.  The PassThrough target module has a version for DNN 3 & 4 only.  The modules work with the SQL server data provider only.

Configuration Options

PassThrough Source

Redirect To

The URL of the page on the target site to redirect to.  This page should contain an instance of the PassThroughTarget module.

Encryption Key

Specifies the key to use to encrypt the user data passed from the PassThroughSource module.  This key must match the key used in the corresponding PassThroughTarget module. The encryption key contains a "default" value.  For added security, you should always set this value to your own random value - but make sure you enter the same value in the corresponding PassThroughTarget module's encryption key setting.

PassThrough Target 
Once you create a PassThroughTarget instance, select the Options menu item from the module settings menu to display the Options page.

Redirect To	Page to redirect to after the user session has been established.
Source Database Connection	The database connection string of the source database.  This value should match the SqlDataProvider connection string from your source portal's web.config file.
Encryption Key	Specifies the key to use to decrypt the user data passed from the PassThroughSource module.  This key must match the key used in the PassThroughSource module. The encryption key contains a default value.  For added security, you should always set this value to your own random value - but make sure you enter the same value in the corresponding PassThroughSource module's encryption key setting.
Synchronize Security Roles	If set, the PassThrough Target module loops through the roles the "source" user is in, and if roles with matching names exist in the "target" portal, synchronizes the role assignment based on the "security role setting" for that role.
Security Role Settings	If the "Synchronize security roles" option is set, you can configure the way the PassThrough module handles synchronization with each security role. Synchronize with source:  If the source portal has a security role with the same name the user is added or removed from roles in the target portal so that role assignments match the roles assigned in the source portal. Always Add Users to this role:  All passed-through users are automatically added to the role. Never Add Users to this role:  Passed-through users are never added to the role, even if they were in the role in the source portal. Any new roles added to the target portal will be set to "Synchronize with source".  For security reasons, the PassThrough module does not allow automatic addition to the "Administrators" role.
If the user already exists:
Passwords	Synchronize:  The password of the target portal is automatically set to the password from the source portal. Require matching passwords:  If set, the password of the user must match in both the source and target sites, or an error message is displayed.  If the user does not already exist in the target portal, the user record is created - but for subsequent visits, the passwords must match.
Email Address	Synchronise:  The email address of the target is automatically set to the email addres from the source portal. Require Matching Email Address:  If set, the email address of the user must match in both the source and target sites, or an error message is displayed.  If the user does not already exist in the target portal, the user record is created - but for subsequent visits, the email addresses must match.

Special Notes

Database access:  The server on which the "target" DotNetNuke portal resides must be able to access the "source" DotNetNuke database.  If your source and target portals are on different machines, you may need to configure your firewall to allow SQL server traffic between them (TCP port 1433).

Password rules in DNN 3:  DNN 3 requires a minimum password complexity - the password must be at least 4 characters.  DotNetNuke 2.1.2 did not have this restriction, and end-users with a DNN 2.1.2 password that does not meet the minimum complexity requirements of DNN 3 will not be able to navigate to the new site, and will encounter an error message.  If necessary. you can change this setting in web.config (changing this setting is not recommended).

<membership userIsOnlineTimeWindow="15">
  <providers>
    <add name="DNNSQLMembershipProvider" type="DotNetNuke.Security.Membership.DNNSQLMembershipProvider,
      DNNSQLMembershipProvider"
      connectionStringName="SiteSqlServer" 
      enablePasswordRetrieval="true" 
      enablePasswordReset="true" 
      requiresQuestionAndAnswer="false" 
      minRequiredPasswordLength="4" 
      minRequiredNonalphanumericCharacters="0" 
      requiresUniqueEmail="false" 
      passwordFormat="Encrypted"
      applicationName="/" 
      description="Stores and retrieves membership data from the local Microsoft SQL Server database" />
  </providers>
</membership>

Sites in Virtual Directories:   DotNetNuke sets several cookies in order to optimise it's performance.  When you configure multiple DotNetNuke instances inside virtual directories on the same Internet Information Server (IIS) instance, IIS assumes that they are part of the same application, and shares cookies between them - but the cookie values are not valid across different portal instances.  As a result, if you set up multiple DNN sites in virtual directories, you will get a "Bad Data" cryptography error when you transfer between portals.  This is not a PassThrough module limitation - you will get the same error if you log on to both sites in the same browser session and transfer between them.  To avoid this error when you have multiple sites set up on a single machine, configure your IIS with multiple "web sites" rather than "vitual directories". 

Security Considerations:   The PassThrough modules automatically create user records and place the user records in security roles.  In order to do this, the PassThrough source module passes information identifying the user to the PassThrough target module in the querystring.  This information is encrypted.  The modules assume that a "matching" user is a user with the same "user name" in both portals. 

You can limit the possibility of users creating a user name in your "source" portal that matches a user that already exists in the "target" portal and using the PassThrough modules to "impersonate" that user by using the "Require matching email address" and "Require matching password" options documented in the section "PassThroughTarget options" (above).

Conditions of use
Permission is hereby granted, on a Try-before-you-buy basis, to any person obtaining a copy of the Inventua DNN PassThrough modules and associated documentation files (the "Software"), to use the Software without restriction, including the rights to use, copy or otherwise use the software for commerical or non-commercial use, but excluding any rights to reverse engineer or remove Inventua logos and licensing information. This permission does not imply or otherwise grant any rights to any other Inventua intellectual property including but not limited to logos, trademarks, documentation and software products.

Special Licensing: The PassThrough source and target modules require one another in order to function, and are therefore licensed for use as a single product for use on two or more DNN portal instances that you are configuring as a "group".  That is - if you configure the modules to make a "group" of two, three or more portal instances work together, you only need to purchase a single license for the PassThrough modules.

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This help file, the accompanying software and other materials supplied with the software are Copyright © Inventua, 2006. All Rights Reserved.

About DotNetNuke
The Inventua DNN PassThrough modules are DotNetNuke portal modules. For more information on DotNetNuke, visit http://www.dotnetnuke.com.