Latest revision as of 09:53, 13 February 2020

Overview

A transport is a method of delivering security strings and other information to users. The type of transport to be used is configurable. Transports are defined by a users group membership from the Repository/Groups menu. A user should only belong to one group. A group may be made up of several repositories, each with differing data sources and data fields, for information on configuring these see Transport Attribute.

Users can send security strings by dual channel, single channel and mobile phone client, and one dual channel transport for User Alerts. PINsafe can work with multiple delivery mechanisms for the Security Strings and User Alerts.

Graphical Single Channel Image and also see Taskbar How to Guide

Mobile Phone Client

Dual Channel, can be SMS or SMTP, see the below guide

Prerequisites

Swivel 3.x

Transport Types

Some of the transport types are listed in the Swivel administration console, but many more are available if the correct java class name is known. For information with working with additional SMS gateways see SMS Gateway Integration.

Additional transport classes may be written either by system integrators or by Swivel Secure. Contact Swivel if an integration is required. An API is available for those wishing to write their own transport class. For further information and location of transports see below under Custom Transports.

Note: When upgrading or moving a Swivel server, remember to include any custom transport classes.

Using a Transport Class

The transport class, without the .class extension is added to the end of: com.swiveltechnologies.pinsafe.server.transport.transport_name

Example: com.swiveltechnologies.pinsafe.server.transport.SmtpTransport

This is added to the required Class on the transport

Select the destination attribute that will determine the user attribute to be used as the message destination. This will typically be "email" or "phone" (or "mobile", depending on configuration).

Select the user group(s) that will be using this transport. The item labelled "Group" is for sending security strings only. "Alert repository group" is for all other messages. In more recent versions, there are two more Group selectors, for Push and Voice. These should only be selected if the transport is designed for two-way communication (either PNATransport or voice transports).

Provided you have selected a destination attribute and a group for at least one message type, after clicking "Apply", a new menu option should appear under "Messaging" for configuring the transport.

Transport values

Transport General Settings

Identifier:

A name for the Transport, this will appear in the Swivel Management Console under Transport, and will allow the transport to be configured. This can be up to 32 characters.

Class:

The java class that this transport uses

Strings per message:

Number of security strings per message. From version 3.6 this uses a referrer to make tracking of security strings possible so that the login can tell the user which security string to use.

Destination attribute:

The attribute that is read from the data source, see Transport Attribute.

Strings Repository Group: previously called Group

Security strings are sent here, and is the group of users that will use this Transport

Alert repository group:

The group of users that will use this Transport for User Alerts information, such as PIN number, account lockout notification, PIN change notification.

Copy security strings to Alert: or Copy to alert transport:

This allows a copy of each dual channel security string to be sent to the User Alerts transport. This feature does not work in Swivel version 3.9.6. but is fixed in 3.9.7.

Transport Formatting

The text in the transports can be configured as required. There are a number of variables that can be used within the transport. Swivel 3.6 onwards also supports the use of HTML see below.

%CR Carriage Return (a new line)

%LF Line Feed (a new line)

%NAME The username

%PIN The PIN number

%PASSWORD PINsafe password where used

%NUMBER Number of the security string sent out

%STRING The Security String

%DAYS Number of days, used for PIN expiry

%TIME The time which a PIN was changed

%DATE The fate which a PIN was changed or warning for inactive accounts

%CODE A code used for reset PIN

%KEY Device Key for PositiveID

3.9.6 allows any user attribute by adding the string

%{attr_name}

Where attr_name is the name of the attribute (the Swivel name, not the repository attribute, it is case sensitive).

HTML in Transports

PINsafe 3.6 allows HTML to be used in the transports. Use the appropriate <a ...> tags.

Note that if you want to use non-ASCII characters in HTML messages, the safest way to do this is to use embedded code entities, for example ¿ will show the inverted question mark used in Spanish. Since looking up these codes is a slow and error-prone process, we have a basic utility program (Windows only) which allows you to enter text, or read in a text file, and will convert it to the relevant codes. This program is available from here.

Transport Settings

These vary according to the transport type, some are given below for clarification

One Time Code message subject is for on-demand messages.

Security String message subject is for normal security strings.

Include header: Options: Y/N this option determines the place holder numbers 1234567890 are displayed to allow the OTC to be found.

Show strings vertically: Options Y/N this option allows the security string and placeholder to be displayed vertically instead of horizontally.

Creating multiple transports of the same type/Creating New Transports

Multiple transports that use the same transport method can be created by creating a new Identifier (Name) for the transport. Creating multiple transports allows groups of users to have:

• Different numbers of security strings
• The same transport types for multiple groups
• Differing transport text or language for different groups of users

Copy the required transport class and remember to set the destination attribute.

The below example shows an second SMTP transport created with the Identifier of SMTP2, the class has been copied from the original version of the SMTP transport

When complete click Apply to save the settings, and a new entry should appear under Transport in the Administration console which can be configured as required.

Custom Transports

For installing custom transports see: Transports Custom Installation

SMTP to SMS

Email with Phone number in email address Mobile_number@domain_name.com use SmtpSmsGateway for the transport Class as below:

 com.swiveltechnologies.pinsafe.server.transport.SmtpSmsGateway

Email with the phone number in the email subject use SmsSubjectTransport for the transport Class as below:

 com.swiveltechnologies.pinsafe.server.transport.SmsSubjectTransport

When all the required fields are complete click Apply to save the settings, and a new entry should appear under Transport in the Administration console which can be configured as required.

Additional Configuration options are:

SMTP Server: The SMTP gateway

Domain: the domain is appended to the email address such as Mobile_number@domain_name

SMTP From: Email from address

Username: Username of the SMS account

Password Password of the SMS account

Domain SMS account domain

Subject Email Subject, for the SmsSubjectTransport this is ignored

SMS Additional Options

Message Overwrite or Replace previous message is supported by some SMS providers.

Flash SMS is also supported by some SMS providers.

SMPP

For SMPP integration see the following SMPP How to guide

Logger Transport

The logger transport sends data to the Swivel Log Viewer as an email transport and is useful for troubleshooting an testing. For further information see Logger Transport.

Known Issues

Swivel version 3.9.6 HTML tags may be displayed in messages and not correctly displayed. Update to a more recent version.

Troubleshooting

If the transport is not correctly formatted

• check the transport text for errors
• For SMS gateways, check the service provider does not reformat or ignore certain parameters or apply filters

Additional information on PINsafe Transport:

Email loses carriage returns

Removing messages from the message queue, see: Message Queue Removal

Resolving Security String Issues

SMS messages are not being sent

Security Strings are not being sent

Transport fails after upgrade

Transport problems

User does not have an associated alert transport

Security String missing place holder 1234567890

Turn off Replace Message or Message Overwrite or Flash SMS and test to see if transport functions

Using HTML in a message Transport_HTML

Error Messages

Loading transport class "com.swiveltechnologies.pinsafe.server.transport.TransportName" failed, error: java.lang.ClassNotFoundException: com.swiveltechnologies.pinsafe.server.transport.TransportName

The java class cannot be found. Possible causes of this error are:

Misspelling of the class name on the transport->general screen

Class file not being in the correct location on the appliance

Class file not having the correct ownership or file permissions

Tomcat has not been restarted