Android
From Swivel Knowledgebase Wiki
Contents |
The PINsafe Android Client Overview
Swivel Secure now offers an Android client for use with the PINsafe platform. This article explains how to download, configure and use this client. For the Java Applet version see Swivlet How To Guide, for the Windows Mobile version see Windows Mobile How To Guide, for the iPhone client see IPhone.
Version 2 of the Android client for additional security provides a security string to the user without entering the PIN.
Requirements
Android Phone
The PINsafe server must be reachable from the mobile phone to receive security strings
Access device for authentication
Security strings must be entered including the comma and sequence number e.g. nnnn,nn
Appliances using PINsafe 3.8 may require an upgrade on their proxy to provision a mobile device, see How to upgrade the appliance proxy for PINsafe 3.8
PINsafe Configuration
Configuring Android user access on the PINsafe server
To allow a user to authenticate using a One Time Code from the Android Applet, the user must have the Swivlet/Mobile Client authentication enabled. To do this on the PINsafe Administration console ensure that the group they are part of has access to the Swivlet/Mobile Client under Repository Groups.
Configuring the PINsafe Authentication
PINsafe can authenticate users using the mobile client to authenticate by RADIUS or Agent-XML authentication
- For RADIUS authentication see RADIUS Configuration Note: The access device must be configured to use PAP for authentication.
- For Agent-XML authentication see XML Authentication Configuration
Mobile Provisioning
PINsafe 3.8 and higher requires each mobile phone to be provisioned so it can be uniquely identified. Ensure that all Mobile Client users have suitable Transports configured to receive their Provision Code. To provision the mobile client select the user and click Re-provision. Earlier versions of PINsafe do not need to use a Mobile Provision Code.
Android Installation and Configuration
Installing the Android Client
The PINsafe Android client is available from the Android Marketplace and can be downloaded directly onto the mobile phone.
Alternatively to find the application go the Android Marketplace https://market.android.com and search for "pinsafe".
The pinsafe.apk file may also be uploaded by various utilities such as Droid Explorer, the Android Marketplace is the preferred method of deployment. A PINsafe version for testing is available here PINsafe Android Client
Configuring the Android Client
When you launch the Android Client you will see the Settings option on the main screen.
Select this option and you will see the settings that need to be entered to use the client.
These settings will generally be provided by the PINsafe System administrator.
The settings are
- PINsafe Version The Version of the PINsafe server. Default pre 3.8, Options pre 3.8 or 3.8 and above
- User Your username that you use when you authenticate via PINsafe
- Webservice URL The URL from where the client can download security strings (or keys)
- Webservice Port The port number used by the webservice. For an appliance this is 8443, for a software install this is 8080
- Webservice Context The context used by the webservice. For an appliance this is proxy, for a software install this is usually pinsafe
Once you have entered the settings return to the main PINsafe screen.
Mobile Provision Code
PINsafe versions 3.8 and higher require each Mobile device to be Provisioned with a Code sent from the PINsafe server. To provision a phone see Mobile Provision Code. PINsafe versions earlier than PINsafe 3.8 do not need to be provisioned.
Downloading Security Strings
At the main menu, test the settings by Selecting the Update Keys option, at the prompt select Yes to confirm to update the keys. This will attempt to retrieve Security Strings from the PINsafe server.
You will see a brief message stating Updated Keys and then if all is well the display will return to the main menu.
If there are any problems an error message will be displayed.
You can confirm that keys have been downloaded by going to the Enter PIN screen and Entering you PIN. (Note: Version 2 does not ask for PIN entry but for additional security provides an OTC). Once you have entered your PIN you will see you extracted one-time code and the number of Security Strings (Keys) you have remaining. The PINsafe server will display the following log message Security strings fetched for user: username
The first time you do this after downloading keys, the Keys Remaining will show as 98.
Using the Android Client to Authenticate
To use the PINsafe Android Client to authenticate is very simple.
- Open the application on your Android
- Select the Enter PIN Option (Note: Version 2 does not ask for PIN entry but for additional security provides an OTC)
- Enter your PIN using the Android keypad displayed.
- The client will show the OTC that you need to enter, (as shown above)
- Enter the OTC into the authentication dialogue, including the ',' and the following 2 digits. e.g. 0947,00
If you need to authenticate again you can select the refresh option
Using the Android Client with ChangePIN
The client can be used in conjunction with the PINsafe changePIN application to allow a user to change their PIN.
For the PINsafe version 2 Android Client, the ChangePIN feature is deprecated. To use ChangePIN, view a security string and use the details to obtain an OTC and generate a new OTC.
For the version 1 client the user first accesses the change pin application in their computer browser then selects the Change PIN option on the Android Client
On the PINsafe client page you first enter your current PIN, then on the next screen you enter you New PIN.
The next screen then displays the two OTCs you need to enter within the Change PIN dialogue in your browser.
Updating Keys
The client downloads 99 keys at a time and these keys are used one at a time until there are none left. However a new set of 99 keys can be downloaded at any time by using the Update Keys. Downloading keys requires network connectivity so it is recommended that you download a new set of keys before the Android Client is likely to be without network connectivity for any length of time.
Testing
When downloading security strings, the following messages should be seen Security strings fetched for user:
Known Issues and limitations
The current version only supports one device per user.
Older versions of the Android client only supports numbers for the authentication string rather than letters. If letters are set on the PINsafe server then a security string of -1,-1,-1,-1,00 is displayed. The current version supports numbers and letters.
PIN numbers may be from 4 to 8 digits in length
Version 2.0 of the client has a changePIN button, but pressing it has no effect. The ChangePIN button has been deprecated, see ChangePIN above.
Troubleshooting
Is the PINsafe server accessible on the internet
Check the connection settings to the PINsafe server
Check the PINsafe logs for any error messages
Can the phone access the internet
If a RADIUS connection is seen from the access device to the PINsafe server but authentication fails, try using PAP
Download new security strings to the phone and retest
Is the OTC being entered with the comma and last two digits. E.g. 7329,62
If the proxy port (8443) on the appliance is being used, ensure that it supports the proxy request of the key retrieval using AgentXML. If this is the case then contact Support for an updated version of the Proxy.
The PIN cannot be entered, version 2 of the client. For security the option to enter the PIN has been removed, instead a security string is displayed.
Error Messages
Incorrect settings - please check your settings
The settings for downloading the security strings are incorrect. Verify what has been entered, and check what the values should be.
Timed Out
The settings for connecting to the PINsafe server may be incorrect or the port is being blocked.
Error occurred whilst fetching security strings for user: graham, error: The user does not belong in the correct group within the user repository to continue the authentication attempt.
The user does not have permissions to use the Mobile client or Swivlet.
Host is unresolved
Hostname cannot be found, check the settings
Message Connection to http://IP_or_Hostname:8080 refused
The IP address, hostname, or port may be incorrect and the server has refused to allow a connection from the client
Failure Please check your settings or try again later
This can be caused by a PINsafe Android Client configured to use PINsafe 3.7 accessing PINsafe version 3.8.
Message: SSL handshake failure: I/O error during system call, Unknown error: 0
This is caused by an SSL request being made against a non SSL server, check the PINsafe Android Client Settings.
Tested Mobile Phones
The following phones have been tested
| Manufacturer | Model | Version | OS Version | Operator | Compatible Y/N | Applet Version |
| Samsung | Galaxy | i9100 | Android 2.3.3 | O2 | Y | 1 |
| Samsung | Galaxy | i9100 | Android 2.3.3 | O2 | Y | 2 |
Keywords: Android, Client, PINsafe, Swivlet, App, marketplace
