Third Party Apps

Overview

OATH authentication allows a mobile device to be prompted for a new OTC (One Time Code) every 60 seconds without requiring a connection to AuthControl Sentry.

Optionally, this timestep can be changed to every 30 seconds. This specific configuration allows for compatibility with third-party applications such as Google Authenticator and Microsoft Authenticator.

Prerequisites

  • Swivel AuthControl Sentry v4 onwards.

Swivel Core Configuration

In order for a user to use the mobile app as an OATH token, they must be allocated the right to use the OATH mode of operation. This is done by ensuring that they are a member of a group that has this right.

Configuring OATH Policy Settings

On the Swivel Administration console, select Policy -> Mobile App and ensure the settings below are configured:

  • Set Mobile App OATH Mode to Yes.

  • Set Use 30 second timestep for OATH to Yes.

  • Configure Issuer for OATH token label. This sets the label displayed within the user’s authenticator app (e.g., “Company VPN”). Please note that spaces in this label can cause issues at present.

Warning

Push Authentication Compatibility

The 30-second timestep mode is not compatible with Push authentication.

Standard OATH (60-second timestep) is compatible with Push authentication, provided that local mode is not also enabled. However, enabling the 30-second mode required for third-party apps prevents the server from sending the necessary push requests.

Provisioning for Third Party Apps

When 30-second mode is enabled, provisioning differs slightly from the standard procedure:

  • QR Code Only: Provisioning can only be done using the QR code. You cannot use the standard URL provisioning link with third-party apps.

  • URL Placeholder: If you are customizing the provisioning message template, note that for 30-second mode, the URL placeholder must be url5, rather than url4.

Tip

Download Email Template

We have created a sample HTML email template specifically designed for Microsoft Authenticator provisioning.

Download Microsoft Authenticator Template

See also

See the article on Email template customisation for more details on message templates.

Transitioning Modes

You can have a mix of 30-second and 60-second timestep tokens on the same server, but not for the same user simultaneously.

  • New Tokens: Changing the setting only affects new tokens created after the change.

  • Existing Tokens: It does not change or invalidate tokens created before the change.

Define a Group of Mobile OATH Users

On the Swivel Administration console, select a group of users that will be using Mobile OATH authentication.

  1. Locate the group in the User Administration list.

  2. Ensure the OATH box is ticked.

  3. Click Apply.

Testing

To test the configuration:

  1. Go to the User Administration screen.

  2. Select a user configured for Mobile OATH.

  3. Click the App Provision button.

Troubleshooting

Common Error Messages

Check the Swivel logs for the following error messages:

CANNOT_CREATE_TOKEN for the <username> user does not belong to the OATH Group

  • Cause: The “App Provision” button was clicked, but the user does not have OATH permissions.

  • Solution: Add the OATH right to the group the user is a member of - make sure a User Sync was performed to absorb the group change.

OATH token does not allow the authentication

  • Cause: A token has not been generated for the user.

  • Solution: When you click “App Provision”, ensure a token is created. Go to the OATH -> OATH Tokens screen and verify a new token exists for that user.

  • Check: If the token has not been created, ensure that the policy Mobile App OATH Mode is set to Yes.