Login App — technical description and configuration

The Pointsharp Login App is a method to authenticate users. The App provides two-factor authentication and is a corporate branded app that makes it easy and secure to login and access cloud and on-premises applications.

By using push notifications, the user is instantly notified when authenticating, and only needs to click a button to complete the authentication.

Pointsharp Login App also supports OATH OTP Tokens and by that covers both one-time-password and push notification in one and same App. The tokens are imported with QR code scanning. This guide will focus on how to get started with the Login App when using push notifications.

Technical summary

The Pointsharp Login App is a security token that uses OTPs for authentication purposes. It relies on the open HOTP standard from OATH to create OTPs. The App uses an out-of-band communications channel to send messages to the authentication server (Pointsharp ID). Users of the Login App never have to remember, copy, type, or in any other way handle the one-time passwords, the app uses them automatically in the background.

The Pointsharp Login App is available for the following platforms:

  • Apple iOS

  • Google Android

Assumptions

Throughout this guide there are vital configuration parameters that are specific for each environment and needs to be updated to reflect each installation. The table below lists these parameters and assumes that the reader understands that some of these parameters needs to be changed to reflect the local environment.

Authentication method name

The guide uses the name ”Login App Default”. This may be changed if required.
Title

The guide uses “Pointsharp Services” as value for the title. The title value can be used to reflect the resource name the user wants to access i.e. VPN, OWA or Skype for Business. This name will be included in the push notification.
Request URL

This guide uses https://push.contoso.com. This is the URL that the app will use to communicate with Access Gateway. This URL must be updated to reflect customers' installation and must match the name described in the prerequisites sections, regarding DNS requirement.
Company

The guide uses Pointsharp AB. Should be updated to reflect the correct company name. This name will be displayed inside the Login App, effectively branding the app.

Onboarding

In any security solution, the onboarding process is a critical element. The initiation of the Login App is very easy to complete by the user. The user only needs to scan a QR-code in the locally installed Pointsharp User portal. The QR-code includes the seed for the token as well as the URL where the App should communicate.

Discover Process

When the App has been initiated, it makes a request to the URL that was included in the QR code to collect configuration data. This data includes branding information as well as contact information.

Authentication

Authentication process overview

The image below gives an overview of the authentication process of the Pointsharp Login App. Please note that the sequence outlined below assumes that the user submits the correct credentials and has a configured Login App.

  1. User submits username and password to the access server.

  2. Credentials are validated by Pointsharp ID.

  3. A push notification request is sent to Amazon SNS.

  4. Amazon SNS sends the push notification request to the proper service (APNS / GCM)

  5. The push notification is sent to the device.

  6. The user “confirms” the ongoing authentication request. The app sends a request to accept the ongoing authentication, signed with an OTP.

  7. Pointsharp ID validates the confirmation by authenticating the OTP.

  8. The user is logged in.

    login app authentication process overview

Authentication sequence diagram

The following sequence diagram shows the authentication process. The diagram below has four major sections.

  1. Initiation process.

  2. Challenge process.

  3. Response process.

  4. Result process.

For a more detailed explanation of each step, please see below.

login app sequence diagram

Configuration

This section covers the necessary prerequisites as well as the configuration steps needed to setup and configure the different components necessary to use the Login App. While the section focuses on the setup of the Login App it will also contain examples of configurations for protecting specific resources.

Prerequisites

As shown in the authentication overview image, a solution using the Pointsharp Login App for authentication purposes makes use of several components. Below is a list of the minimum requirements.

Requirement Note

Pointsharp ID Server

Pointsharp Access Gateway

Push notification account (recommended)

Required for push notifications.

DNS

An external DNS name, pointing to the Pointsharp Access Gateway, is required for the Login App communication.

Certificate

A SAN for the external DNS name must be added to the Pointsharp Access Gateway, certificate.

Pointsharp ID

Below are the required configuration steps that needs to be done to configure Pointsharp ID for Login App authentication:

Add password authentication method

For the default setup, a password authentication method is required. Please note that most installations already have such a method configured.

  1. Start Pointsharp ID Admin GUI.

  2. Go to the Authentication tab.

  3. Click Add.

    1. Type: Password.

    2. Name: Login App Password

    3. Under additional settings, choose if Pointsharp Password is to be used (if not, AD passwords will be used).

  4. Click OK.

  5. Click Apply.

  6. Go to the General tab.

  7. Click Restart.

Add Login App authentication method

Create an authentication method to be used with the Login App. The example below is a Default setup which does not specify which resource the user logs on to.

  1. Start Pointsharp ID Admin GUI.

  2. Go to the Authentication tab.

  3. Click Add.

    1. Type: PointsharpLogin

    2. Name: Login App Default

    3. Title: Pointsharp Services

  4. Authentication method: Choose the authentication method to be used as the first factor with the Login App.

  5. If push notifications should be used, enable push notification.

  6. Click OK.

  7. Click Apply.

  8. Go to the General tab.

  9. Click Restart.

login app authentication method

Parameter Description

Title

This text will be shown in Pointsharp Login application as "To {Title} Confirm" or replace {title} in push notification. If title value is received from Gateway, it’s value will be used before this method title.

Wait Timeout (seconds)

The timeout value for when to stop checking current login status. This is used for all authentication except via Gateway Login Forms.

Wait Interval (seconds)

The time to wait before method continue to check current login status.

Authentication Method

Choose a configured authentication method to be used for authentication together with Pointsharp Login. None: Pointsharp Login will skip password validation and only validate via Pointsharp Login App.

Security Options

Advanced security options: Enforce Biometrics, QR Challenge and Geo Restriction. Enabling any of these options will disable action buttons in push notification because of security reasons. See Security options.

User Domain Removal

Enable this functionality if PointSharp ID should remove any UPN suffix or "DOMAIN\" prefixes in the incoming username.

Advanced Options

More options to change default behavior of this authentication method.

Cache Settings

Settings to enable PointSharp ID to re-use past authentication decisions. Useful when you don’t want to require Pointsharp Login App validation for each authentication attempt.

Third Party Redirect

Settings to decide how Pointsharp Login App will behave on Confirm.

Never

Is default, do nothing special, continue as usual.
Automatic

On Confirm button clicked automatic launch third party app.
Manually

A third button is shown together with Confirm/Decline and let user decide to launch third party app or not. Default third party app is Skype for Business.

Security Options

login app authentication security

Parameter Description

Enforce Biometrics

All Login App Confirm/Decline requests will require biometrics verification. Biometrics login will popup on Confirm/Decline only if Login App isn’t using biometrics. To activate a biometric lock on the app itself, see Enforce Biometrics. Push Notification Confirm/Decline doesn’t have this functionality.

QR Challenge

All Login App Confirm requests will require QR scanning verification. Push Notification Confirm/Decline doesn’t have this functionality.

Location Rule

Choose which location rule do be used for geo restriction. Push Notification Confirm/Decline doesn’t have this functionality.

Expire Time

How old the last known location can be before it is invalid, based on last known location timestamp and current time.

Push notification

To use Pointsharp Login App with push notifications, a push notification account is required. This is set by default when creating a Login App Authentication Method in PSID Admin GUI.

login app push

Parameter Description

Enable

Enable/disable to send push notification to login app.

Notification

Choose a notification method to send push notifications with.

Message

Message text that is shown by the push notification. Message has two variables which are replaced: {username} replaced with the user’s username, and {title} is replaced with the title defined in Gateway configuration for Pointsharp Login application, or title in this method. The title from Gateway will be chosen first.

To create a new push notification method, go to PSID Admin GUI > Notification > Pointsharp Push.

Parameter Description

Type

Notification type.

Name

Set a name for the notification.

Username

Access Key ID of Amazon Simple Notification Service.

Password

Access Key Password of Amazon Simple Notification Service.

Login App token configuration

The next step is token configuration.

  1. Start Pointsharp ID Admin GUI.

  2. Go to the Tokens tab.

  3. Select Pointsharp Login.

  4. Request URL: https://push.contoso.com.

  5. Click Apply.

  6. Go to the General tab and click Restart.

Access Gateway

Before protecting a resource, the Access Gateway must be configured to receive the communication from the Login App. A Setup Wizard has been added to the Access Gateway Admin GUI, which will guide you through all the steps.

Below are the required configuration steps that needs to be configured in the Access Gateway when not using the setup wizard, to support Login App authentication.

Add modLoginApp module

The modLoginApp module is responsible for reading and acting upon the Login App communication and relays necessary information to Pointsharp ID.

  1. Start the Access Gateway Admin GUI and right click on Modules.

  2. Choose Add Module; this will start the module wizard.

  3. Click Application.

  4. Click Next.

  5. Select Pointsharp Login App and click Next.

  6. Name: Login App Connect.

  7. Company Name: This company name will be visible in the Pointsharp Login Application.

  8. Authentication Method: Login App Default. The name of the method to use when authenticating towards the Pointsharp ID.

  9. Click Next.

  10. Click Apply.

Create listener for request URL

This is the hostname the Login App will use to communicate, note that the address must reflect the value in request URL.

  1. Start the Access Gateway Admin GUI and right click on Listeners.

  2. Choose Add Listener; this will start the listener wizard.

  3. Click Next.

  4. Address: push.contoso.com

  5. Scroll down to Rules: and click Add.

  6. Name: Root

    1. Still in Rules: Scroll down, click Add under Module configuration names.

    2. Select the Pointsharp Login App module previously created. (in this example: Login App Connect)

    3. Click OK.

  7. Click OK.

  8. Click Next.

  9. Click Apply.

  10. Click Publish to save and publish the configuration.

Publishing resources

This section contains an example of configuration that can be used for different published resources. It also contains an example of the configuration necessary to support access servers using the RADIUS protocol against Pointsharp ID to authenticate users. Please note that every example assumes that the previous sections in this guide has been completed.

Add modForms module

The modForms module provides the form-based authentication that requires the user to enter credentials.To add a modForms Module follow the following steps:

  1. Start the Access Gateway Admin GUI and right click on Modules.

  2. Choose Add Module; this will start the module wizard.

  3. Click Authentication.

  4. Click Next.

  5. Select Form-Based Authentication and click Next.

  6. Name: Login App Default

  7. Authentication Methods: click Add.

  8. Type: Pointsharp Login

  9. Authentication Method: Select a Login App Authentication Method. (In this example we use: Login App Default). The name of the method to use when authenticating towards the Pointsharp ID.

  10. Friendly name: Login App Default

  11. Click Next.

  12. Click Apply.

  13. Click Save in the top right corner.

Multiple login options (Failovers)

If you want the users to have multiple login options or use a secondary authentication method as failover (SMS, mail or any other non-login app authentication methods); you can add them in the Authentication Method list found in your modForms Module.They will be shown in a dropdown list on the login page.

Edit publishing rule

This section outlines the necessary steps to change to a Login App authentication towards an existing resource.The guide assumes that the resource is correctly published in the Access Gateway with an existing authentication module and that access is working correctly.

Change authentication method

To change from the current authentication to the Login App authentication, follow these steps:

  1. Start the Access Gateway Admin GUI and expand the Listener.

  2. Select the rule with an existing Authentication Module. (Example:“/OWA/”)

  3. In the Module configuration names list, right-click the existing modForms module and choose remove.

  4. Click Add under Module configuration names.

    1. Select the Login App Default in the drop-down menu.

    2. Click OK.

  5. Mark the newly added modForms module and move it to be first in the rule order. (modForms modules must always be on top while KCD should always be last).

  6. Click Publish in the top right corner to Save and Publish changes.

If multiple rules for same listener has Authentication modules, and you want login App authentication for all of them, make sure to do these changes on each rule.
If an existing modForms module is active on the publishing rule: Instead of removing it, you do have the option to right-click and choose Edit. But if the existing modForms module is used on multiple publishing rules, the changes will affect all publishing rules. That’s why we choose to show how to remove and then add a new module instead of editing the existing one.

Pointsharp Login App over RADIUS

server using the RADIUS protocol to authenticate users requesting access.

Add Pointsharp Login method

  1. Start Pointsharp ID Admin GUI.

  2. Go to the Authentication tab.

  3. Click Add.

    1. Type: PointsharpLogin

    2. Name: RADIUS Login App

    3. Port: Make note of the port assigned to the method.

    4. Title: <title> - This value will be shown in the push notification.

  4. Authentication method: Login App Password

  5. If push notifications should be used, enable push notification.

  6. Click OK.

  7. Click Apply.

  8. Go to the General tab.

  9. Click Restart.

Now you can use the Pointsharp Login App authentication method with your RADIUS client. Configure the access server to use the Login App authentication method by providing the IP of the Pointsharp ID Server and the port of the RADIUS Login App method.

Resource Titles

The title value can be used to reflect the resource name the user wants to access, i.e. VPN, OWA or Skype for Business. This name will be included in the push notification.

In this section we will explain how to choose a title for each resource. Please note that guide below assume that the reader has gone through the previous sections in this guide and understands the basic of Login App configuration and that earlier examples was a Default configuration which could be used to have the same title for all resources.

Add Title to Resource

To add a title for a specific resource you first need to create an authentication method for each and every resource you want to add a title for.

In the authentication method, Name and Title should be associated towards the resource itself.

For example:

Name: LoginApp_OWA

Title: Outlook Web Application (OWA)

Creating modForms Modules

When the Authentication method is in place, you also would need to add a modForms Module for each resource.

This time it is recommended to name the module after the specific resource.

For example:

Name: LoginApp_OWA

Edit Publishing Rules

When all the modForms are connected to the authentication methods for each and every resource, publish these new modules onto existing publishing rules.See Edit publishing rule.

Now when using these specific configurations for the resources, the Title will reflect the resource name that the user wants to access.

Third Party Redirect

Third Party Redirect is a setting (see Add Login App authentication method) that decides how the Pointsharp Login App will behave when the user inside the login app itself is pressing Confirm. This gives the login App an option to redirect the user towards the resource you logged in to.

For example: If logging in towards Skype for Business with the Login App, when pressing Confirm, the App can redirect the user to the Skype for Business app so the user doesn’t have to open it manually.

There are 3 options when it comes to Third Party Redirect:

Never

Is default, does nothing special, continue as usual.
Automatic

When clicking the Confirm button, third party app will launch automatically.
Manually

A third button is shown together with Confirm/Decline and let the user decide to launch the third-party app or not.

Default third party app is Skype for Business, but can be changed on the specific login app authentication method in your PSID3.xml file found on your Pointsharp ID Server.

Biometrics

The users have the option to activate a biometric lock on the app itself. Whenever the user opens the app, they will be prompted by a biometric lock. This is configured inside the app itself (found under Menu/Settings). The Biometrics lock will be using the same Biometrics that is configured on the phone itself.

Users will still be able to “Confirm / Decline” through the push notification as long as “Hide Notification” is not checked, in the login App Authentication Method.

Enforce Biometrics

In the Access Gateway modLoginApp Module you have the option to activate Enforce Biometrics which will automatically enforce the biometric app lock for all users.

Enforce Biometrics for users with specific AD attributes

To be able to Enforce Biometrics on specific users you need a working Login App configuration.

  1. Create a new modLoginApp where Enforced Biometrics is active.

  2. Create a new Rule for your Login App communication listener. Example: “/enforced“ (Make sure the rule is above the Root rule in rule order).

  3. Add the new Enforced Biometrics modLoginApp to your new Rule.

  4. Go to your regular modLoginApp module, or press Go to Module from the Root rule of your Login App communication listener.

  5. Press Add on Multiple Login Server.

    1. Choose witch AD attribute that should be used.

    2. Choose which pattern found in the attribute that should trigger Enforced Biometrics.

    3. Type the URL towards your newly created rule. (Example:https://push.contoso.com/enforced).

  6. Start Pointsharp ID Admin GUI.

  7. Go to the Authentication tab.

  8. Click on the Authentication method that you use in your Login App Setup.

  9. Click Edit on Advanced Options.

  10. Go to User Attribute and add the Attribute chosen to be used on your Multiple Login Server.

  11. Click OK, OK again, go to General and do a Restart of your PSID Admin.

Passwordless

When Configuring the Login App it is possible to remove the password requirement. This means that users only have to type in their username and would still receive the Login App 2-factor.

For security reasons we do not recommend using this option if Push is enabled.

PSID configurations

Add Login App Authentication Method:

  1. Start Pointsharp ID Admin GUI.

  2. Go to the Authentication tab.

  3. Create a Login App method and give it a friendly name.

  4. Enable User Attribute under Advanced Options.

  5. Change Authentication Method to None.

  6. Click Apply.

  7. Go to General and Restart the Pointsharp ID Service.

Access Gateway configurations

The Password field can automatically be removed when you activate passwordless on a chosen authentication method used in the Access Gateway. Passwordless can be chosen either directly from the Access Gateway Setup Wizards when publishing a resource using modForms, or whenever you are adding/editing an authentication method in an existing modForms module. This is easily done by checking the box Passwordless.

Branding the About Page

When the configuration is complete, it is highly recommended to brand the About tab found in the Pointsharp Login App, to make it point towards your company’s contact information/details.

The branding is based on a regular HTML configuration found on your Access Gateway server. The Default path is: "…​\Pointsharp\Gateway\www\PublicResources\Login\app\about.html"

Please note that this could vary depending on the installation path for your Access Gateway.

To encode an image to base64 format, we recommend the following site: https://www.base64encode.org/

Simplified enrollment

See Simplified enrollment of the Login App