Active Directory

Active Directory (AD) is a technology created by Microsoft that provides a variety of network services, including:

• Lightweight Directory Access Protocol LDAP is the industry standard directory access protocol, making Active Directory widely accessible to management and query applications;
• Kerberos-based authentication;
• DNS-based naming and other network information;
• Central location for network administration and delegation of authority;
• Information security and single sign-on for user access to networked based resources;
• The ability to scale up or down easily, etc.;

MassTransit allows you to authenticate Web client contacts and Client contacts using Active Directory (AD) instead of assigning them a MassTransit login name and password. Web client contacts can be created automatically and maintained based on groups defined in Active Directory. Privileges for file exchange between users can be based on existing AD groups. This ensures that users will have the broadest possible access to send files through MassTransit to other users in their organizations.

You can set up MassTransit HP to use Single Sign-On (SSO) for Web client contacts for easier connections. MassTransit allows Active Directory users connected to an Active Directory-enabled MassTransit HP Server to log into MassTransit automatically using their domain credentials, instead of having to type their name and password. This technology, known as Single Sign-On (SSO), works with popular browsers on Windows and Mac OS X when connecting to an IIS web server.

The MassTransit Log Viewer can now be enabled to allow any user with a valid Active Directory account, who is in a defined group, to view the MassTransit log without requiring a web client license or plug-in.

NOTE: Be aware that MassTransit’s Directory Services integration currently supports Active Directory on a supported Windows server platform. Currently, MassTransit can only integrate with a single domain.

Go to top

Active Directory (AD) authentication can be used on MassTransit HP and MassTransit SFTP servers. You can use this kind of authentication for the following contacts:

• on MassTransit HP servers – Web client contacts;
• on MassTransit SFTP servers – Client contacts.

To use AD authentication, you need to complete the following requirements:

• on MassTransit HP servers:
      - a configured domain;
      - MassTransit Web (MTWeb) configuration is already completed;
• on MassTransit SFTP servers:
      - a configured domain.

To enable and configure directory services, follow these steps:

    1. Open the MassTransitEngine.cfg file located in the MassTransit installation directory. By default, this folder is placed on the system drive in:
         a. on 32-bit machines:
            i. MassTransit SFTP: ~\Program Files\Group Logic\MassTransit SFTP
            ii. MassTransit HP 7.0: ~\Program Files\Group Logic\MassTransit Server 7
           iii. MassTransit HP 7.1 and later: ~\Program Files\Group Logic\MassTransit Server
         b. on 64-bit machines:
            i. MassTransit SFTP: ~\Program Files (x86)\Group Logic\MassTransit SFTP
            ii. MassTransit HP 7.0: ~\Program Files (x86)\Group Logic\MassTransit Server 7
           iii. MassTransit HP 7.1 and later: ~\Program Files (x86)\Group Logic\MassTransit Server

NOTE: All lines beginning with "%%" in the MassTransitEngine.cfg file are considered commented and therefore ignored. Please ensure that all settings you change are uncommented (if you see "%%" characters at the beginning of any of the settings you modify, delete them).

    2. To enable the directory services in general, find the Directory Services Settings section and set the DIRECTORY_SERVICES_ENABLED setting to TRUE, as shown bellow:
         DIRECTORY_SERVICES_ENABLED=TRUE

    3. Under the same section, enter the name of the domain you want MassTransit to use; PRIMARY_DOMAIN= setting. This will be the domain that LDAP will append queries to. Include the fully qualified domain name, e.g., mydomain.com.

    4. Set the IP address of the LDAP server; LDAP_SERVER_ADDRESS= setting.

NOTE: For secure connections, you must specify the DNS (domain name system) name as it appears in the certificate for your LDAP server, not the IP address.

    5. Set the port number that will be used for the communication with the LDAP server; LDAP_SERVER_PORT= setting. The default port number for non secure connections is 389. For secure connections, the default port is 636.

    6. Specify whether the connection to the LDAP server is secured or not by configuring the LDAP_USE_SECURE_CONNECTION = setting:
         a. for an non secure connection, configure the setting as shown below:
            LDAP_USE_SECURE_CONNECTION = false
         b. for secure connection:
            LDAP_USE_SECURE_CONNECTION = true

    7. Configure the distinguished name and password of objects which will be used to bind them to the LDAP directory:
         a. To set the name that will be used, you need to specify its properties starting from the lowest LDAP directory level to the highest one: first, the account username, then, the group the account belongs to, and the levels above if there are any. Separate the properties with commas (,).
            LDAP_BIND_DN=CN=USERNAME,CN=Users
         b. Specify the password of the account that was set above:
            LDAP_BIND_PASSWORD=PASSWORD

NOTE: The LDAP_BIND_DN and LDAP_BIND_PASSWORD flags may be left blank to indicate that MassTransit will bind to the LDAP server as the currently logged in Active Directory user. In this case, the machine must be bound to the domain and the MassTransit service must be running as the AD user that MassTransit will use to bind to the LDAP server. To configure the MassTransit service, open the Services console, highlight the service named "MassTransit", right click and select Properties. Then, go to the Log On tab, select the "This account" option, enter the account name and password, and select OK.

    8. If the bind user (stated under the LDAP_BIND_DN= setting) is not in the primary domain (configured under the PRIMARY_DOMAIN= setting), uncomment this line and specify the bind user's domain:
         LDAP_BIND_DOMAIN=bind.domain.com

    9. When you create new contacts which will authenticate via Active Directory, you need to search for their accounts in the LDAP tree. You have to specify the location in the LDAP tree where you want MassTransit to search for the accounts; LDAP_SEARCH_BASE=CN= setting. If you want to specify multiple locations, you must separate them with a semicolon (;) (e.g. CN=Users;OU=Staff). If LDAP_SEARCH_BASE is left blank, searches will begin at the root of the tree.  A search base is not required, but may improve performance for large trees.
         LDAP_SEARCH_BASE=CN=Users

   10. To control the scope of the LDAP searches, configure the LDAP_SEARCH_SCOPE= setting with one of the following values:
         a. LDAP_SEARCH_SCOPE=BASE – setting this value will allow MassTransit to search for AD objects only on the level specified in the LDAP_SEARCH_BASE= setting;
         b. LDAP_SEARCH_SCOPE=ONELEVEL – allows MassTransit to search for accounts on the level specified in the LDAP_SEARCH_BASE= setting and one level under it;
         c. LDAP_SEARCH_SCOPE=SUBTREE – allows MassTransit to search for accounts on the level specified in the LDAP_SEARCH_BASE= setting and on all levels under it.

   11. If you want to make ActiveDirectory the default authentication method for Web client and Client contacts, set the USE_DIRECTORY_AUTHENTICATION_BY_DEFAULT= setting to TRUE. Otherwise, the default method will be MassTransit.
         USE_DIRECTORY_AUTHENTICATION_BY_DEFAULT=TRUE

   12. Once you have completed the above steps, you will need to restart the MassTransit Engine for the changes to take effect.

Go to top

The directory services settings located within the MassTransitEngine.cfg configuration file are configured to search the Active Directory "Users" folder by default (step 9 of the Configuring Active Directory Authentication section); however, they may be modified to search Organizational Units (OUs) instead.

This may be an optimal configuration for administrators that wish to create a "MassTransit Users" organizational unit, without impacting the standard "Users" folder.

The following is a procedure to make the necessary modifications:

    1. Open the MassTransitEngine.cfg file located in the MassTransit installation directory. By default, this folder is placed on the system drive in:
         a. on 32-bit machines:
            i. MassTransit SFTP: ~\Program Files\Group Logic\MassTransit SFTP
            ii. MassTransit HP 7.0: ~\Program Files\Group Logic\MassTransit Server 7
           iii. MassTransit HP 7.1 and later: ~\Program Files\Group Logic\MassTransit Server
         b. on 64-bit machines:
            i. MassTransit SFTP: ~\Program Files (x86)\Group Logic\MassTransit SFTP
            ii. MassTransit HP 7.0: ~\Program Files (x86)\Group Logic\MassTransit Server 7
           iii. MassTransit HP 7.1 and later: ~\Program Files (x86)\Group Logic\MassTransit Server

NOTE: All lines beginning with "%%" in the MassTransitEngine.cfg file are considered commented and therefore ignored. Please ensure that all settings you change are uncommented (if you see "%%" characters at the beginning of any of the settings you modify, delete them).

    2. Locate the configuration option: LDAP_SEARCH_BASE=CN=

    3. Adjust the LDAP_SEARCH_BASE setting to reflect your custom Organizational Unit. For example:
         LDAP_SEARCH_BASE=OU=Your_Organizational_Unit,DC=Your_Domain,DC=COM

NOTE: This configuration example reflects an Organizational Unit that resides within the root of the LDAP directory structure. If the Organizational Unit resides elsewhere, the OU= parameter will need to reflect the exact location of the OU within the tree.

The search base may actually contain any part of the directory tree. In such configurations, the AD Administrator must specify the Fully Qualified Domain Name (FQDN) without the DC= connection strings. For example:
         LDAP_SEARCH_BASE=CN=Development,OU=MassTransit


Go to top

To create a contact with Active Directory Authentication in the MassTransit Administrator, follow these steps:

    1. In the MassTransit Administrator, open the Contacts window by clicking on the Contacts button from the Navigation Bar or by selecting Contacts in the Window main menu.

    2. Click on the Add Contact... button.

    3. In the Contact Information window that appears, select the Web Client option from the Entry Is... drop-down menu in the General tab.

    4. In the Authentication section of the General tab, select the Active Directory option.

    5. In the Account field, enter the user login name in either of the following formats:
         - username@domain.com
         - DOMAIN\username.

    6. Click on the Search button; once the user is found in the directory, a green light will appear which means that the contact is found in the Active Directory groups configured in the Configuring Active Directory Authentication section.

    7. Once a contact configured to use Active Directory authentication has been found, the corresponding contact information from Active Directory will populate to the Contact Information fields on the General Tab. All of the populated information from Active Directory is read-only and cannot be modified in the MassTransit Administrator.

    8. Configure the desired contact privileges following the steps on the Contacts page.

    9. When you are ready with the contact configuration, click OK in the Contact Information window to save the contact to the Contacts list.


Go to top

NOTE: Logging on the MassTransit server via MTWeb is available on MassTransit HP servers only.

In order to log in the MassTransit server via MTWeb using an Active Directory user, follow these steps:

    1. Open a supported web browser.

    2. Open the login web page of the MassTransit server.

    3. Enter your Active Directory logon name in any of the following formats:
         - username;
         - username@domain.com;
         - DOMAIN\username.

    4. Enter your Active Directory password.

    5. Click on the Login button to log into the server.

Now you should be able to use the designated for that contact MTWeb functionalities.


Go to top

In order to log in the MassTransit server via FTP using an Active Directory user, follow these steps:

    1. Open a supported web browser or a stand-alone FTP client.

    2. Open the FTP login page of the MassTransit server.

    3. Enter your Active Directory logon name in any of the following formats:
         - username;
         - username@domain.com;
         - DOMAIN\username.

    4. Enter your Active Directory password.

    5. Click on the Login button to log into the server.

Now you should be able to use the functionality designated for that contact.


Go to top

NOTE: The automatic Active Directory account management feature is only available in MassTransit HP.

MassTransit implements the automatic Active Directory account management feature that allows setting up MassTransit contacts, forwarding privileges and so on, automatically based on existing Active Directory groups.

Since MassTransit 6.0, you are allowed to leverage the groups in your Active Directory tree to automatically create accounts and assign forwarding privileges. Any existing Active Directory group can be designated as a part of the MassTransit Master List (MML) or the MassTransit Distribution List (MDL) or both.

MassTransit will automatically create contacts for Master List members. MassTransit will create contacts for Distribution List members when those members attempt to log in to MassTransit or when they are forwarding files. The Distribution List defines forwarding privileges – contacts who are members of an Active Directory group included into the Distribution List are automatically allowed to forward files to all other members of the same Active Directory group and all its subgroups, if any. MassTransit contacts for Distribution List members are created dynamically when they are needed and are set to expire 7 days after the creation date. Any file transfer related operation that involves a Distribution List contact, such as files being added to that contact’s mailbox or forwarded from another contact, will extend its expiration date to be at least 7 days from the time the operation occurred.

MassTransit polls Active Directory periodically to synchronize both Master and Distribution List membership. Automatically created MassTransit contacts that no longer have a membership in either of the Lists will be automatically deleted from the contacts database.

All automatically created MassTransit contacts will be of the Web client type.


Go to top

To configure the automatic Active Directory account management, follow the instructions bellow:

    1. Open the MassTransitEngine.cfg file located in the MassTransit installation directory. By default, this folder is placed on the system drive in:
         a. on 32-bit machines:
            i. MassTransit SFTP: ~\Program Files\Group Logic\MassTransit SFTP
            ii. MassTransit HP 7.0: ~\Program Files\Group Logic\MassTransit Server 7
           iii. MassTransit HP 7.1 and later: ~\Program Files\Group Logic\MassTransit Server
         b. on 64-bit machines:
            i. MassTransit SFTP: ~\Program Files (x86)\Group Logic\MassTransit SFTP
            ii. MassTransit HP 7.0: ~\Program Files (x86)\Group Logic\MassTransit Server 7
           iii. MassTransit HP 7.1 and later: ~\Program Files (x86)\Group Logic\MassTransit Server

NOTE: All lines beginning with "%%" in the MassTransitEngine.cfg file are considered commented and therefore ignored. Please ensure that all settings you change are uncommented (if you see "%%" characters at the beginning of any of the settings you modify, delete them).

    2. There is a master switch that enables or disables the whole feature – LDAP_AUTO_ACCOUNT_MANAGEMENT_ENABLED. Accepted values are TRUE or FALSE; the default is FALSE. Set the value to TRUE as shown below:
         LDAP_AUTO_ACCOUNT_MANAGEMENT_ENABLED=TRUE

NOTE: This parameter will be ignored and the feature will be disabled if the core Directory Services feature is disabled or fails to initialize.

    3. Enter a valid Active Directory group(s) that you want to include in the MassTransit Master List as a value of the LDAP_MML_GROUPS= setting. A group must be specified by its distinguished name, such as CN=Group Name,CN=Users,DC=domain,DC=com. When you want to set more than one group, enter a semicolon (;) between the groups to be used as a separator.

NOTE: Duplicate, nested, or recursively nested groups are acceptable and will not result in any issues at run time. However, only manually created Active Directory groups with explicitly defined user account membership can be designated as entries in the Master List. Built-in Active Directory security principals that establish implicit group membership, such as Domain Users, will be ignored by the automatic Active Directory account management.

    4. Enter a valid Active Directory group(s) that you want to included in the MassTransit Distribution List as a value of the LDAP_MDL_GROUPS= setting. To enter more than one group in the Distribution List, use a semicolon between the groups to separate them. Same requirements and limitations apply to this parameter as the Master List set in the previous step.

NOTE: MassTransit 7.2 and later offers new option to allow members of different MDL groups to send files to each other.

    5. To allow members of different MDL groups to send files to each other set the LDAP_ALLOW_USERS_TO_SEND_BETWEEN_MDL_GROUPS= value to true, the default is false.

    6. Set a profile account name whose settings will be propagated to all automatically created accounts as a value of the LDAP_AUTO_ACCOUNT_PROFILE= setting. The specified account should be the name of an existing Web client contact. If the profile contact is not specified, does not exist, or is not a Web client, MassTransit will use the default Web client contact settings when automatically creating contacts. The following profile settings are overridden for automatically created contacts:
         a. Authentication type – always set to Active Directory;
         b. Contact information block (first name, last name, e-mail, etc.) – populated from the respective Active Directory account;
         c. Account expiration time – not set for Master List contacts; for Distribution List contacts it is set to either the profile expiration time or 7 days from the current time, whichever is greater, or based on the LDAP_MDL_ACCOUNT_EXPIRATION=7 setting, if set.
         d. Accept Calls From User – always on;
         e. Receive Files From User – always on;
         f. Send Files To User – always on;
         g. Allow Connect Via Web To Transfer Files – always on;
         h. Manually assigned forwarding privileges – only propagated to Master List contacts.

    7. For contacts that belong to the MML you can use a separate profile account rather than using the LDAP_AUTO_ACCOUNT_PROFILE= setting. You can specify it using the LDAP_MML_PROFILES= value. Use any existing MassTransit web contact account for this value. When setting up this contact in the MassTransit Administrator under the Mailbox tab you MUST choose the Default Mailbox option. Only settings found in the Contact Information Security tab are propagated to new contacts.
         a. If LDAP_MML_PROFILES is not specified, MML contacts will be created with the account profile set under the LDAP_AUTO_ACCOUNT_PROFILE setting;
         b. If a single profile is specified, all MML contacts will be created with that profile;
         c. If different MML groups should use different profiles, a semicolon separated list of profiles can be specified that will be used on a one-to-one relationship with the lists specified in LDAP_MML_GROUPS=.

    8. Set the polling interval (specified in minutes) for the Master List as a value of the LDAP_MML_POLLING_INTERVAL= setting. The default value for this parameter is 30 minutes; using shorter intervals is not recommended.

    9. Set a valid integer number that will represent the polling interval (specified in minutes) for the Distribution List as a value of the LDAP_MDL_POLLING_INTERVAL setting. The default is 60; using polling intervals less than 30 minutes is not recommended.

    10. Set the maximum number of Web client contacts to maintain in the database at any given time as a value of the LDAP_MAX_WC_ACCOUNTS setting. Set this to a valid integer number; the default is 3000; the minimum is 3000 (values below the minimum will be overridden); for Ad hoc delivery, this maximum is observed with or without AD services. The set number includes both automatically and manually created contacts. This parameter is provided to avoid accidentally creating very large numbers of contacts due to various configuration errors.

   11. Set the maximum number of forwarding contacts to be displayed in the Web client (and/or Ad hoc contact) user interface in the LDAP_MAX_FWD_CONTACTS setting. Set this to a valid integer number; the default value is 3000.

   12. When you are ready with configuring the automatic account management, save and close the MassTransitEngine.cfg configuration file.

   13. In order to apply the saved changes immediately, you need to restart the MassTransit Engine.

The configuration of the automatic Active Directory account management is completed.


Go to top

The new MassTransit Distribution List (MDL) capability defines who can send files to whom. The MDL is a regular Active Directory Security Group containing users and other groups. It can be an existing group or a specially created group. For members of the MDL MassTransit creates accounts on demand, only when they are needed, and makes these users available as valid destinations for files to be transferred. These on demand accounts are automatically purged after a period of time and are recreated when needed.

Users that are members of an AD group, which is part of the MDL, can send files to the other members of the same AD group and to any users on child levels by default. MassTransit 7.2 and later allows users that are members of MDL group to send files to any member of the other MDL groups.
Below are three examples of MDL configuration that will help you understand how this feature works.

Example1:

In the first example, the MassTransit Distribution List – “MDL Group A” contains two AD groups – “Group Dog” and “Group Cat”. Each of the two groups has two members. The members of “Group Dog” can send files only to each other. The same is valid for the members of “Group Cat”.
For example: “Gracy AD user” can send files only to “Bob AD user”.

Example2:

In the second example, the MassTransit Distribution List – “MDL Group A” contains two AD groups – “Group Dog” and “Group Cat” and two AD users – “Jake AD user” and “Rex AD user”. These users can send files to each other, as well as to all users that are on child tree levels – the members of “Group Dog” and “Group Cat”. The members of “Group Dog” can send files only to each other. The same is valid for the members of “Group Cat”.
For example: “Rex AD user” can send files to ” Jake AD user”, “Gracy AD user”, “Bob AD user”, “Tim AD user”, and “John AD user”. “Tim AD user” can send files only to “John AD user”.

Example3:

In the third example, there is one additional AD group – “Group Snake” which belongs to “Group Dog”. “Sammy AD user” and “Sally AD user” are on the lowest tree level of the MDL, so they can send files only to each other. In contrast to the previous example, users from “Group Dog” can send files not only to each other but to members of “Group Snake” as well, since it is also a member of “Group Dog”. “Rex AD user” and “Jake AD user” can send to all users.
For example: “Bob AD user” can send files to “Gracy AD user”, “Sammy AD user” and “Sally AD user”. “Tim AD user” can send files only to “John AD user”, since “Sammy AD user” and “Sally AD user” are not on a child tree level.

Go to top

MassTransit allows you to configure an Active Directory user group which allows any user with a valid Active Directory account, who is in a defined group, to view the MassTransit log online (in the MassTransit web site) without requiring a web client license or plug-in.

Follow the steps below to enable the MassTransit Log Viewer for an authorized group:

    1. Open the mtweb.ini file located in the MTWeb directory. By default, this folder is placed on the system drive in:
         ~\Program Files\Group Logic\MassTransit 7
         On 64-bit versions of Windows, the default location of the MassTransit folder is on the system drive in:
         ~\Program Files (x86)\Group Logic\MassTransit 7

NOTE: All lines beginning with a semicolon (;) in the mtweb.ini file are considered commented and therefore ignored. Please ensure that all settings you change are uncommented (if you see ";" characters at the beginning of any of the settings you modify, delete them).

    2. Go to the APPLICATION section of the file.

    3. Add the AuthMethod_LogViewingGroup authentication method by uncommenting the line below and commenting out the line immediately after.
         ; AUTHENTICATE_METHODS = "AuthMethod_SOAP,AuthMethod_LogViewingGroup"
         AUTHENTICATE_METHODS = "AuthMethod_SOAP"

NOTE: The order of the AUTHENTICATE_METHODS flag can be reversed. If the original order of the flags is used (AUTHENTICATE_METHODS = AuthMethod_SOAP,AuthMethod_LogViewingGroup), then a Web client, that is both a MassTransit contact with Active Directory authentication and a member of the authorized log viewing group, will be navigated to the MassTransit plug-in once authenticated. The only way that user will be able to view the Log is if privileges are given to that individual user via the MassTransit Administrator when the account is created or edited; then, the Log tab will be present in the user interface of the Web client. If the current order of the flags is reversed (AUTHENTICATE_METHODS = AuthMethod_LogViewingGroup,AuthMethod_SOAP), then the user will be navigated to the Log Viewer, but will not be navigated to the plug-in for file transfer. The default approach is recommended.

    4. Configure the AUTHORIZED_LOG_VIEWING_GROUP setting appropriately with the Active Directory group that will control the log access. This will be the Active Directory group whose members can view the MassTransit log without having a contact in the Contacts window of the MassTransit Administrator application.
         AUTHORIZED_LOG_VIEWING_GROUP="CN=MT_LOG_VIEWER,OU=GROUPS,DC=YOUR_DOMAIN,DC=COM"

    5. Once you’ve completed the above steps, you will need to restart IIS and the MassTransit Engine for the changes to take effect:
         a. Open the IIS Manager from Start → Administrative Tools → IIS Manager and click on the Restart button in the administration console of IIS.
         b. Open the Services console from Start → Administrative Tools → Services and highlight the MassTransit service. Click on the Restart button.


Go to top

NOTE: Single sign-on is not available on MassTransit SFTP servers.

Since MassTransit 5.1, there is a feature that allows Active Directory users connected to an Active Directory-enabled MassTransit HP Server to authenticate to the MassTransit MTWeb interface without typing a username and password. This technology, known as Single Sign-On (SSO), works with popular browsers on Microsoft Windows and Mac OS X when connecting to an IIS web server.

The end result is an environment that is more streamlined and intuitive for end users, and helps administrators to better manage their MassTransit systems in a larger computing environment.

Before configuring Single sign-on, you need to complete the following requirements:

• MassTransit HP is installed and running;
• MassTransit is properly configured to access an Active Directory domain or forest for authentication;
• MTWeb has been properly configured for use.

Go to top

The server running the SSO-enabled MassTransit MTWeb components must be bound to the organization's Active Directory domain. This will allow the web server (Microsoft Internet Information Services) to pass credentials received via the web browser to MassTransit and Active Directory for authentication. If the machine is not bound, or if you are unsure, ask your organization's network administrator for assistance.

When you have completed the requirements stated above, you can configure SSO following the steps corresponding to your available web server (IIS).

To configure single sign-on on Internet Information Services (IIS) 6, follow the steps below:

    1. Launch Internet Information Services (IIS) Manager from Administrative Tools on your Windows server.

    2. Right-click on the Web Site hosting the MTWeb interface. Click Properties.

    3. In the resulting dialog, click the Documents tab:
         a. Ensure that the Enable default content page check box is selected.
         b. Click on the Add... button, and in the Add Content Page dialog, type sso.php. Click OK.
         c. Move sso.php to the top of the list by clicking the Move Up button. Ensure sso.php is listed above index.php, if it exists.

    4. Click on the Custom Errors tab. The Error messages for HTTP errors section has a list of HTML documents used when IIS encounters an error.
         a. Six (6) 401 errors are listed. For each 401 error, highlight the error and click on the Edit... button.
         b. In the appeared window, ensure Message type is File.
         c. Click on the Browse... button to locate the 401.html file that is provided in the MTWeb components. This file is generally located in the following location:
            i. for 32-bit machines:
               - MassTransit HP 7.0 – C:\Program Files\Group Logic\MassTransit Server 7\MTWeb\webroot\401.html
               - MassTransit HP 7.1 and later – C:\Program Files\Group Logic\MassTransit Server\MTWeb\webroot\401.html
            ii. for 64-bit machines:
               - MassTransit HP 7.0 – C:\Program Files (x86)\Group Logic\MassTransit Server 7\MTWeb\webroot\401.html
               - MassTransit HP 7.1 and later – C:\Program Files (x86)\Group Logic\MassTransit Server\MTWeb\webroot\401.html
         d. Apply this new file to all 401 errors.
         e. Click OK to continue.

    5. Right-click on the sso.php file in the web site root inside Internet Information Services (IIS) Manager. Click Properties.

    6. Click the File Security tab:
         a. In the Authentication and access control section, click the Edit... button.
         b. In the Authentication Methods dialog that appears, ensure the Enable anonymous access check box is not checked and ensure Integrated Windows authentication check box, under the Authenticated access section, is checked.
         c. Click OK, then click OK again.

    7. Open the PHP configuration file, php.ini, in an application suitable for plain text edit. The file is located in the php folder, generally on the system drive in C:\php:
         a. Find the option session.save_path and set this to "C:\php\sessiondata" (including the quotation marks) as shown below. If this option is commented out (preceded by a semicolon (;) ), remove the comment to make it active.
            session.save_path = "C:\php\sessiondata"
         b. Save and close the php.ini file.

    8. The sessiondata folder in the previous step may not already exist inside C:\php. If this folder does not exist, it must be created:
         a. Navigate to C:\php and right-click. Select New, then select Folder. Name the folder sessiondata.
         b. Right-click on the sessiondata folder and click Properties.
         c. Click the Security tab.
         d. Add privileges for the Internet Guest Account (IUSR_COMPUTERNAME) and the local Users group by clicking the Add... button:
            i. Click on the Object Types... button, and select Users and Groups. Click the OK button.
           ii. Click Locations... and select the computer in the Locations window that appears. Click the OK button.
           iii. In the Select Users or Groups window, click on the Advanced button.
           iv. Click the Find Now button. Select both the Internet Guest Account IUSR_COMPUTERNAME and the local Users group by clicking the first, holding down the CTRL key, and clicking the second.
            v. Click OK, then click OK.
           vi. Inside the sessiondata Properties window, click the Internet Guest Account user (IUSR_COMPUTERNAME), and, under Permissions for... section, allow Full Control and click OK.
           vii. Highlight the IUSR account and click the Advanced button. In the "Advanced Security Settings for sessiondata" window check the box next to Replace permission entries on all child objects with entries shown here that apply to child objects.
          viii. In the Security dialog that appears next, click Yes.
           ix. Repeat for the Users group.
            x. Click OK.

    9. Navigate to the folder where MTWeb is located. This is generally:
         a. on 32-bit machines:
            i. MassTransit HP 7.0: ~\Program Files\Group Logic\MassTransit Server 7
            ii. MassTransit HP 7.1 and later: ~\Program Files\Group Logic\MassTransit Server
         b. on 64-bit machines:
            i. MassTransit HP 7.0: ~\Program Files (x86)\Group Logic\MassTransit Server 7
            ii. MassTransit HP 7.1 and later: ~\Program Files (x86)\Group Logic\MassTransit Server

   10. Right-click on MTWeb, then click Properties. Similar to the previous step, allow Read & Execute permissions for the Internet Guest Account and the local Users group. Do not set advanced permissions for the child objects.

   11. Inside the MTWeb folder, set the permissions for the parsed and templates_c folders. If these folders are not empty, delete their contents with exception of the readme.txt files, prior to completing this step. Apply Full Control permissions for the Internet Guest Account and the local Users group on the parsed and templates_c folders. Also, set the advanced permissions for child objects for the parsed and templates_c folders (like in Step 8d).

   12. Restart IIS by right-clicking on the machine name in the left-hand pane of the IIS Manager, selecting All Tasks and choosing Restart IIS…. In the Stop/Start/Restart… dialog that appears, choose Restart Internet Services on MachineName, and click OK. IIS will restart.

Configuration of single sign-on is now complete for your MassTransit MTWeb server.

Under certain circumstances it might be necessary to maintain both single sign-on and regular authentication mechanisms for the same MassTransit MTWeb server. If that should be the case, follow the steps in the Configuring Single Sign-On and Regular Authentication on the Same MassTransit Server section.


Go to top

To configure single sign-on on Internet Information Services (IIS) 7, follow the steps below:

    1. Open the IIS Manager from Start → Administrative Tools → IIS Manager.

    2. In the Connections pane, expand the server name, expand Sites then click on the Default Web Site entry (or whichever entry is configured to host the MTWeb interface) to display the IIS configuration Home pane.

    3. Double click Default Document from the Home pane.
         a. Under the Actions pane, click Add…
         b. In the Name: filed, enter "sso.php" (no quotations).
         c. Move the "sso.php" to the top by clicking Move Up from the Actions pane. Ensure sso.php is listed above index.php, if it exists.

    4. Under the Connections pane, click on the Web Site hosting the MTWeb interface. Then, double click Error Pages. There is a list of HTML documents used when IIS encounters an error.
         a. Highlight error 401 and click on the Edit... button from the Actions pane.

         b. In the appeared Edit Custom Error Page window, select the Execute a URL on this site radio button.
         c. In the URL (relative to site root) field, enter the following:
            /401.html
         d. Click OK.

    5. Under the Connections pane, click on the Web Site hosting the MTWeb interface. Then, double click Authentication. If you do not see Windows Authentication on the list of authentication methods, you will need to install that from the Server Manager. If you see Windows Authentication in the list of methods, skip to step 6.
         a. Close the IIS Manager and go to Administrative Tools → Server Manager.
         b. On the left, click on Roles.
         c. Under Role Services click Add Role Services.
         d. In the Select Role Services window, scroll down to the Security (Installed) section.
         e. Check the box for Windows Authentication. Then click Next, Install and Close.
         f. Reboot the server to ensure these changes take effect.
         g. Go back to the IIS Manager.

    6. Under the Connections pane, click on the Web Site hosting the MTWeb interface. Then, double click Authentication:
         a. Highlight Anonymous Authentication from the appeared list and click on the Disable button from the Actions pane, if enabled.
         b. Highlight Windows Authentication and click on the Enable button from the Actions pane to enable it.

    7. Open the PHP configuration file, php.ini, in an application suitable for plain text edit. The file is located in the php folder, generally on the system drive in C:\php:
         a. Find the option session.save_path and set this to "C:\php\sessiondata" (including the quotation marks) as shown below. If this option is commented out (preceded by a semicolon (;) ), remove the comment to make it active.
            session.save_path = "C:\php\sessiondata"
         b. Save and close the php.ini file.

    8. The sessiondata folder in the previous step may not already exist inside C:\php. If this folder does not exist, it must be created:
         a. Navigate to C:\php and right-click. Select New, then select Folder. Name the folder sessiondata.
         b. Right-click on the sessiondata folder and click Properties.
         c. Click the Security tab.
         d. Add privileges for the Internet Guest Account (IUSR) and the local Users group by clicking the Add... button:
            i. Click on the Object Types... button, and select Users and Groups. Click the OK button.
           ii. Click Locations... and select the computer in the Locations window that appears. Click the OK button.
           iii. In the Select Users or Groups window, click on the Advanced button.
           iv. Click the Find Now button. Select both the Internet Guest Account IUSR and the local Users group by clicking the first, holding down the CTRL key, and clicking the second.
            v. Click OK, then click OK.
           vi. Inside the sessiondata Properties window, highlight the Internet Guest Account user (IUSR) and click on the Edit... button. Then, under Permissions for... section, allow Full Control and click OK.
           vii. Highlight the IUSR account and click the Advanced button. In the "Advanced Security Settings for sessiondata" window, click the Edit... button.
          viii. Highlight IUSR from the appeared list and check the box next to Replace permission entries on all child objects with entries shown here that apply to child objects and click OK.
           ix. In the Windows Security dialog that appears next, click Yes.
            x. Repeat for the Users group.
           xi. Click OK.

    8. Navigate to the folder where MTWeb is located. This is generally:
         a. on 32-bit machines:
            i. MassTransit HP 7.0: ~\Program Files\Group Logic\MassTransit Server 7
            ii. MassTransit HP 7.1 and later: ~\Program Files\Group Logic\MassTransit Server
         b. on 64-bit machines:
            i. MassTransit HP 7.0: ~\Program Files (x86)\Group Logic\MassTransit Server 7
            ii. MassTransit HP 7.1 and later: ~\Program Files (x86)\Group Logic\MassTransit Server

    9. Right-click on MTWeb, then click Properties. Similar to the previous step, allow Read & Execute permissions for the Internet Guest Account and the local Users group. Do not set advanced permissions for the child objects.

   10. Inside the MTWeb folder, set the permissions for the parsed and templates_c folders. If these folders are not empty, delete their contents with exception of the readme.txt files, prior to completing this step. Apply Full Control permissions for the Internet Guest Account and the local Users group on the parsed and templates_c folders. Also, set the advanced permissions for child objects for the parsed and templates_c folders (like in Step 8d).

   11. Restart IIS by right-clicking on the on the MassTransit Web Site entry under the Connections pane and then click Restart from the Actions pane. IIS will restart.

Configuration of single sign-on is now complete for your MassTransit MTWeb server.

Under certain circumstances it might be necessary to maintain both single sign-on and regular authentication mechanisms for the same MassTransit MTWeb server. If that should be the case, follow the steps in the Configuring Single Sign-On and Regular Authentication on the Same MassTransit Server section.


Go to top

In order to maintain both single sign-on and regular authentication mechanisms, you need to configure SSO for your web server first and then complete this configuration. If you haven't configure SSO, follow the steps corresponding to your available web server (IIS6, or IIS7) above and get back to this section again.

    1. Make sure you have configured single sign-on as described above.

    2. Open the Internet Information Services (IIS) Manager.

    3. Right click on the Web Site hosting the MTWeb interface and select New → Virtual Directory…

    4. The Virtual Directory Creation Wizard opens up. Click on the Next button.

    5. Assign an alias to the virtual directory, such as NoSSO, and click Next.

    6. Browse to the same location on disk as pointed to by the web site hosting the MTWeb interface and click Next. By default, this location is:
         a. for 32-bit machines:
            i. MassTransit HP 7.0 – C:\Program Files\Group Logic\MassTransit Server 7\MTWeb\webroot
            ii. MassTransit HP 7.1 and later – C:\Program Files\Group Logic\MassTransit Server\MTWeb\webroot
         b. for 64-bit machines:
            i. MassTransit HP 7.0 – C:\Program Files (x86)\Group Logic\MassTransit Server 7\MTWeb\webroot
            ii. MassTransit HP 7.1 and later – C:\Program Files (x86)\Group Logic\MassTransit Server\MTWeb\webroot

    7. Make sure Read, Run Scripts (such as ASP) and Execute (such as ISAPI applications or CGI) check boxes are checked and click Next.

    8. Click on the Finish button.

    9. In the Internet Information Services (IIS) Manager, right click on the newly created virtual directory and select Properties.

   10. In the resulting dialog, click the Documents tab:
         a. Ensure the Enable default content page check box is selected.
         b. Click Add..., and in the Add Content Page dialog, type index.php. Click OK.
         c. Move index.php to the top of the list by clicking the Move Up button. Ensure index.php is listed above sso.php, if it exists.
         d. Click OK.

   11. Restart IIS by right-clicking on the machine name in the left-hand pane of the IIS Manager, selecting All Tasks and choosing Restart IIS…. In the Stop/Start/Restart… dialog that appears, choose Restart Internet Services on MachineName, and click OK. IIS will restart.

Configuration of the regular authentication entry point to the MTWeb web site is done now. Users not wishing or not being able to use the single sign-on mechanism will be able to navigate to the MassTransit authentication page directly by appending the web site's URL in their browser with /NoSSO. For example, if the user is connecting to http://masstransit.company.com, he should type the following in the web browser and then click Go or press Enter:
    http://masstransit.company.com/NoSSO


Go to top

Under certain circumstances, it might be necessary to maintain both single sign-on and regular authentication mechanisms for the same MassTransit MTWeb server. At this time, IIS 7 does not support this kind of dual mode configuration. Users not wishing or not being able to use the single sign-on mechanism will have to navigate to the MassTransit authentication page directly by appending the web site’s URL in their browser with /index.php. For example, if the user is connecting to http://masstransit.company.com, he should append /index.php to this address, and then click Go or press Enter in their web browser to connect to:
    http://masstransit.company.com/index.php


Go to top

Due to security considerations, modern web browsers will not automatically provide authentication information to web sites unless they are part of your local intranet or explicitly defined within the browser’s configuration parameters. This ensures that authentication information is not sent to a malicious web site inadvertently, which could compromise organizational security.

These next sections will assist you in configuring various browsers to use the single sign-on feature with your SSO-enabled MassTransit HP MTWeb instance.

Before configuring your web browsers, make sure the following requirements are completed:

• The client machine must be bound to Active Directory in order for this feature to function properly;
• The current logged-in user must have a valid Active Directory account, and this account must be associated with a contact within MassTransit;
• For Mac OS X, Kerberos must be properly configured and a valid ticket granting ticket (TGT) must be active for the logged-in user;
• If any of the following conditions is present on the client machine:
      - the client machine is not presently bound, or,
      - is accessing from a remote location where authentication to the Active Directory infrastructure is not possible, or,
      - if the connecting user has a valid MassTransit account that is not associated with Active Directory,
  then MTWeb users will be presented with a NTLM authentication dialog on Microsoft Windows and Mac OS X. Users in these circumstances can "fall back" to the legacy MTWeb login page by dismissing the dialog by clicking the Cancel button, or pressing Escape. Due to the way these NTLM authentication dialogs work, they will not accept login names for MassTransit contacts that are not associated with Active Directory. Instead you must use the "fall back" feature and login from the legacy MTWeb login page.

• NTLM Dialog:

Apple Safari on Mac OS X does not directly support this ability to "fall back" and therefore, in order to use the standard MTWeb login page, the user must append index.php to the MTWeb address, which then bypasses the single sign-on component.

For example, if you are connecting to http://masstransit.company.com, the user should append index.php to this address, and then click Go or press Enter in their web browser to connect to http://masstransit.company.com/index.php.

Firefox allows you to define "trusted" sites using hostnames, IP addresses or combinations - including wildcards - that authentication data should be automatically passed to. These steps apply for Firefox versions 3 or later on both Microsoft Windows and Mac OS X.

    1. Launch Firefox.

    2. In the Address Bar, enter about:config and then press Enter. In the warning message that appears, click the I'll be careful, I promise! button. A very long list of configuration parameters for Firefox will be displayed.

    3. Using the Filter textbox, type network.negotiate. Five (5) options will be returned.

    4. Double click on the network.negotiate-auth.trusted-uris option:
         a. In the resulting dialog, enter the hostname or IP address of the SSO-enabled MTWeb host. Acceptable inputs are as follows:
            - IP address (i.e. 10.10.20.80)
            - Hostname (i.e., masstransit.company.com)
            - Wildcards (i.e., .company.com or 10.10.20.*)
            - Separate multiple entries with a comma (i.e., masstransit1.company.com,10.10.20.80)

         b. Once entered, click OK.

    5. Restart Firefox.

Single sign-on configuration for Firefox is now complete. You may test the functionality by visiting your MTWeb installation when bound to Active Directory and authenticated as a user associated with a MassTransit contact. If working properly, Firefox will not prompt you to login. Instead, you will be automatically navigated to the MassTransit File Transfer page. Your Active Directory login, in the form of DOMAIN\USERNAME, will appear in the upper-left-hand corner of the MTWeb interface.


Go to top

Internet Explorer, by default, will automatically provide authentication credentials to sites defined as being part of the Local Intranet. Internet Explorer contains logic that automatically attempts to identify sites on the intranet network. However, due to network layouts and other factors, this may not always work reliably. Therefore, we need to instruct Internet Explorer to consider your MTWeb installation as part of the Local Intranet zone.

    1. Launch Internet Explorer.

    2. From the Tools menu, click Internet Options.

    3. Click the Security tab. Then, click Local intranet.

    4. Click the Sites button.

    5. In the Local intranet dialog, click the Advanced button. In the resulting dialog, add the URLs for your SSO-enabled MTWeb installation. You should provide both the DNS hostname and the IP address for the server. Uncheck the Require server verification (https:) for all sites in this zone check box.

    6. Click Close.

    7. Verify that Internet Explorer's options have not deviated from the default by clicking Custom level… on the Security tab.

    8. Scroll to the bottom of the Settings list. Under User Authentication section, ensure that the radio button for Automatic logon only in Intranet zone is selected. Optionally, you can reset IE to the zone defaults, which are Medium-low.

    9. Click OK. Then click OK in Internet Options to apply your changes.

   10. Restart Internet Explorer.

Single sign-on configuration for Internet Explorer is now complete. You may test the functionality by visiting your MTWeb installation when bound to Active Directory and authenticated as a user associated with a MassTransit contact. If working properly, Internet Explorer will not prompt you to login. Instead, you will be automatically navigated to the MassTransit File Transfer page. Your Active Directory login, in the form of USERNAME, will appear in the upper-left-hand corner of the MTWeb interface.


Go to top

Safari supports single sign-on out of the box, and requires no configuration to use this feature. Safari relies on Mac OS X's support for the MIT Kerberos standard for authentication to connect to single sign-on-enabled services. Active Directory uses Kerberos version 5 for authentication by default.

The Mac OS X machine needs to be bound to the Active Directory domain to allow for single sign-on to be used. This feature works with the built-in Active Directory plug-in and optional third party software, such as ADmit Mac from Thursby Software.

When logging in with an Active Directory user account, Mac OS X will be assigned a Kerberos ticket that dictates the services the user is allowed to use. Safari uses this ticket to connect to the SSO-enabled MTWeb server.

You may test the functionality by visiting your MTWeb installation when bound to Active Directory and authenticated as a user associated with a MassTransit contact. If working properly, Safari will not prompt you to login. Instead, you will be automatically navigated to the MassTransit File Transfer page. Your Active Directory login, in the form of DOMAIN\USERNAME, will appear in the upper-left-hand corner of the MTWeb interface.


Go to top

Other browsers may work, but have not been tested and may not provide the higher levels of security when using SSO. It is recommended that you use the browsers mentioned in this document when accessing your SSO-enabled MTWeb instance.


Go to top

MassTransit allows for authentication of application and web client contacts against Active Directory on Windows 2003 Server and greater. Because MassTransit systems may sit outside of an organization’s firewall in the demilitarized zone (DMZ), it may be necessary to open the ports on a firewall to allow Active Directory queries to pass through.

Ports Used by MassTransit

MassTransit uses TCP and UDP port 389 to communicate with Active Directory. This port number is the default for Active Directory. If your organization uses a different port number, or, if your firewall is configured to do port forwarding/mapping, you can specify this port number in the MassTransitEngine.cfg file, located in the root folder of your MassTransit installation. For instructions on how to configure the Active Directory Authentication refer to the following section: Configuring Active Directory Authentication.

Go to top