Configuring HCL Verse iOS for Certificate-Based Authentication

HCL Verse iOS now supports authentication using client certificates. With client certificate authentication, when a user wishes to access the Traveler server endpoint, the application will be asked to provide the client certificate to complete the SSL handshake and secure the connection for the user. The certificate is then used as long as the certificate remains valid.

Starting with HCL Verse iOS 11.0.6, support was added for Certificate Based Authentication. There is currently only one mode supported: the server (or access gateway) requires the client device to provide a certificate only. Requiring a certificate and userid/password is not supported. Additionally, this version of the client does not alternatively support basic authentication in the event the certificate-based authentication fails.

Prerequisites

  • Minimum App version: 11.0.6
  • Client certificate (PKCS#12) with an additional file extension (.hclmbd) imported into the app keychain.

    Verse iOS supports client certificate of type PKCS#12 (.p12). When generating client certificates, the admin must export them into a PKCS#12 store. Additionally, due to Apple restrictions the .p12 certificate must have a file extension of .hclmbd (example: userCert.p12.hclmbd). This is to prevent the p12 certificate from being imported into the Apple system keychain where Verse iOS cannot access it. For more information about this, refer to the Apple documentation.

  • The email address of the user must be specified when generating the client certificate. This is necessary for HCL Verse iOS to properly create the account.
  • The Common Name of the client certificate is used as the Display Name of the account. When generating the client certificate, it is best to name this to be the user’s full name.

Distribution of client certificates to mobile devices

Currently there is only one mode of distributing the client certificates to mobile devices: email distribution. Once the administrator has generated the certificates, they can be distributed to the mobile devices via email (either via Domino email using Traveler, or via an external email). Once the email is sent to the device it can then be imported by Verse iOS into its own app keychain.

Importing the Client Certificate to the Verse iOS keychain

Note: The client certificate must be imported to the app keychain for the user to authenticate using client certificate. HCL Verse iOS needs to be installed for the certificate import to occur. Certificate import can be done either on an existing OR fresh install of Verse iOS.
There are 2 scenarios where the client certificate may be imported:
Scenario 1: From HCL Verse iOS (as an email attachment)
  1. Open the email with the client certificate as an attachment.
  2. Tap on the attachment. A prompt will pop up stating a client certificate is detected for importing. Press OK.
  3. A prompt for the certificate password will appear. Enter the certificate password provided by the administrator and press OK to validate.
  4. If the password is valid, a new window will pop up showing the certificate. Press Import to proceed with importing the certificate to the app keychain.
  5. A prompt will pop-up to confirm if the import is successful.
Scenario 2: From third party email app (as an email attachment)
  1. Open the email with the client certificate as an attachment.
  2. Tap or long press on the attachment to display the Share options.
  3. Locate the “Copy to Verse” option and press it to launch Verse.
  4. Follow the prompts to import the certificate into the app keychain.

Migrating to Certificate-Based Authentication

Once the client certificate is imported into the app keychain, the user can now migrate from username-password authentication to certificate-based authentication. Currently there is no automatic migration and Verse iOS needs to be uninstalled and reinstalled to use the client certificate for authentication. Refer to the steps below:

  1. Uninstall HCL Verse iOS, then reinstall the application from the App Store. (Skip to step 2 if using a fresh install of HCL Verse iOS).
  2. Launch Verse iOS.
  3. The user is prompted to connect to My Company’s Server. Click to proceed.
  4. Enter the server URL that is configured to require the client certificate. For steps on setting up the server for client certificate authentication. Refer to the documentation for Verse Android.
  5. Click Connect. If the server requires a client certificate, HCL Verse iOS pops up a view with a list of imported client certificates that can be used.
    Note: If there are no imported certificates, Verse displays an error. Therefore, the client certificate must be imported prior to performing these steps.
  6. Select the client certificate to be used. The user will once again be prompted to validate the certificate password.
  7. When validated, the CONTINUE button is enabled. Hit Continue to proceed with the authentication.
  8. If the authentication succeeds, the initial synchronization of the user’s mail, calendar and contacts begins.

Important notes

  • Transitioning from a client certificate only authentication mode to a username-password authentication mode is NOT supported and will require an uninstall and re-install of the HCL Verse iOS application.
  • The client certificate keychain storage is shared with HCL Connections for iOS. If the customer is using the same credentials for Connections and Mail, then the same certificate used with HCL Connections for iOS can be use with Verse and there is no need to import it a second time.