.. toctree:: :maxdepth: 2 :caption: Mobile OATH Configuration ================ 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:`Download Microsoft Authenticator Template ` .. seealso:: 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 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**.