Bypass Codes Guide

What is a Bypass Code

Bypass Codes can be used as an alternative authentication method in the event users misplace their 2nd factor device. A bypass code is a user-specific 9 digit numerical code. When appended to a user’s password, it authenticates them without sending a request to their mobile or desktop app.

Each user can have up to 5 different codes. In order for a user to login using their bypass codes, the domain they are accessing must have bypass code authentication enabled.

A bypass code has 2 attributes:

Expiration Date: A bypass code can be set to expire after a set amount of time (up to one year), or set to never expire. The bypass code can only be used within this time
Uses Allowed: A bypass code can have up to 1000 uses. Once a bypass code has been used up, it can no longer be used to authenticate and a new bypass code must be issued

Unlocking a Token
Each token has a set number of allowed unlock attempts. Any invalid unlock attempt, whether with or without a bypass code, is counted. If the number of invalid unlock attempts reaches the maximum for that domain (default 5) the token is revoked.

Once a token is unlocked, the number of invalid unlock attempts is reset to 0.

Professional, Business or Enterprise subscription required
See the Pricing page for more information about subscription options.

Creating Bypass Codes

There are two methods for creating bypass codes.

Manually

Manual bypass code creation is appropriate when you want to issue a small number of bypass codes. Since bypass codes are user-specific, each bypass code must be generated individually from the desired user’s page.

To manually create a bypass code:

Log in to LoginTC Admin
Click Users
Click on a specific user and navigate to their page:
Click Generate New Bypass Code:
Select options for the expiration time and number of uses allowed:
Click Generate Bypass Code

Programmatically

You can use the powerful LoginTC REST API to programmatically add and manage bypass codes from your application or website. See Bypass Codes documentation for more details.

Managing Bypass Codes

Manually

Bypass codes can be viewed and managed from two different locations on the LoginTC Admin Panel.

Bypass Codes Index

All of the organization’s bypass codes can be viewed and deleted from the Bypass Codes Index page. You can use the search tool to narrow down results.

Log in to LoginTC Admin
Click Bypass Codes:

User’s Pages

Each user’s page has a table displaying their bypass codes. Bypass codes can be viewed, generated, and deleted from here

Log in to LoginTC Admin
Click Users
Click on a specific user and navigate to their page
Scroll down to view the Bypass Codes table

Programmatically

You can use the powerful LoginTC REST API to programmatically view, add, and delete bypass codes. See Bypass Codes documentation for more details.

Administrator Roles Settings

Set the expiration and re-uses limits for non-super administrators.

To configure how non-Super Administrators can create Bypass Codes:

Log in to LoginTC Admin
Click Bypass Codes
Click on Settings:
Select desired limits for expiration and Re-use enabled or disabled
Scroll down to the bottom of the page and click Save

Enabling / Disabling Bypass Codes for a Domain

Although a bypass code is user-specific, they can only be used to access domains that have bypass codes authentication enabled.

To enable or disable bypass codes for a domain:

Log in to LoginTC Admin
Click Domains
Select the domain you want to modify
Click on Settings:
Scroll down to Bypass Codes
Select either enabled or disabled
Scroll down to the bottom of the page and click Update

Using Bypass Codes

When authenticating, a user enters their username normally. In the password field, they should should enter their password followed immediately by a comma and the bypass code.

Regular input (without bypass code) :

    username: john.doe
    password: johnPassword

Input with bypass code :

    username: john.doe
    password: johnPassword,123456789

If the bypass code is valid, the user will be authenticated without a request being sent to their 2nd factor device. If the bypass code is invalid, exhausted, or expired, the user’s request will be denied.

NOTE
There must not be any spaces between the password, the comma, and the bypass code

For more examples see: Bypass Code

Troubleshooting

If your users are having difficulty authenticating with bypass codes, check the Logs page in the LoginTC RADIS Connector web interface:

Log in to your RADIUS connector web UI
Click Logs

Bypass Codes Not Enabled for Domain

If a user is trying to access a domain where bypass code authentication is not enabled, you will find the following error message within their authentication attempt:

    2015-08-28 17:20:25,763 - DEBUG - Checking for bypass code
    2015-08-28 17:20:25,800 - DEBUG - Bypass codes are not enabled for this domain
    2015-08-28 17:20:25,800 - CRITICAL - Invalid credentials for user john.doe

    Exception: Invalid credentials for user john.doe

You can enable or disable bypass code authentication for a domain from the LoginTC Admin App. Click here for more information

Invalid Bypass Code

If a bypass code is detected, you will find the following log messages associated with the user’s login attempt:

    2015-08-28 17:17:51,268 - DEBUG - Checking for bypass code
    2015-08-28 17:17:51,307 - DEBUG - Bypass codes enabled for this domain
    2015-08-28 17:17:51,307 - DEBUG - Possible bypass code detected

    2015-08-28 17:17:51,316 - DEBUG - Verifying bypass code for john.doe
    2015-08-28 17:17:51,316 - DEBUG - Calling-Station-IP is null, not sending originating IP Address
    2015-08-28 17:17:51,384 - CRITICAL - Invalid bypass code

    APIException: Invalid bypass code

In this case, the user may be attempting to use a bypass code that is either: – Expired – Exhausted – Incorrect

You can check the state of a user’s bypass code through the LoginTC Admin Panel, or programmatically through the Rest API. Click here for more information on managing bypass codes

No Bypass Code is Detected

If no bypass code is detected, you will find the following log messages associated with the user’s login attempt:

    2015-08-24 16:15:38,435 - DEBUG - Checking for bypass code
    2015-08-24 16:15:38,474 - DEBUG - Bypass codes enabled for this domain
    2015-08-24 16:15:38,475 - DEBUG - No bypass code detected
    2015-08-24 16:15:38,475 - CRITICAL - Invalid credentials for user john.doe

    Exception: Invalid credentials for user john.doe

In this case, the user is not correctly appending their bypass code to their password. Click here to review the format for entering bypass codes.