PhenixID DocumentationPhenixID Authentication ServicesSolutionsPhenixID One TouchOpen Phenixid OneTouch automatically on same device (autostart)

Open Phenixid OneTouch automatically on same device (autostart)

This document describes how to trigger autostart of the PhenixID OneTouch app when used on the same device as the information channel, for example a mobile web browser.

Autostart is used for end user convenience.

PAS version 4.0 or higher has same device settings as default, no changes needed unless triggered from another app than the mobile system web browser.

Flow

1. Mobile web browser or app is asking for user authentication with PhenixID OneTouch.

2. User enters userID

3. userID is sent to PhenixID Authentication Services. PhenixID OneTouch assignment is created.

4. Web browser or app launches PhenixID OneTouch using a link (how to construct link is described below)

5. User approves assignment in PhenixID OneTouch

6. PhenixID OneTouch returns focus to the calling app

Constructing links

To open PhenixID OneTouch automatically, use this link pattern:

phxidpush://start?return_url=<url_to_return_to>

The return URL value must be URL encoded.

For returning to native apps, the return URL value must start with appschema://

 

Example

Web browser

phxidpush://start?return_url=https%3A%2F%2Fdemo.phenixid.net%2Fauthenticate%2Fotinternal

Native app

phxidpush://start?return_url=novaward%3A%2F%2

Example implementation for iOS devices

An example implementation for iOS devices can be found at https://demo.phenixid.net/OneTouchAutoStart.html

Add to PhenixID Authentication Services template

To add a PhenixID OneTouch autostart link to PhenixID Authentication Services, follow these steps:

1. Open <phenixid_server_root>/mods/com.phenixidentity~auth-http~<version>/templates/onetouchpoll.template

2. Modify the html/javascript code to provide a link for autostart.

App-switching to non-default app

*AnonymousAssignment authenticator

By default, OneTouch will switch back to the system web browser app (Safari on iOS, Chrome on Android).

To use OneTouch app-switching from a non-default app, follow these steps:

  • On the PhenixID server, copy <phenixid_server_root>/mods/com.phenixidentity~auth-http~<version>/templates/anonymousassignment.template. Name the copy custom_anonymousassignment.template.
  • Open custom_anonymousassignment.template in a texteditor.
  • Locate and change anonymousassignment.js to custom_anonymousassignment.js
  • Save the file
  • On the PhenixID server, copy <phenixid_server_root>/mods/com.phenixidentity~auth-http~<version>/web/res/js/anonymousassignment.js. Name the copy custom_anonymousassignment.js.
  • Open custom_anonymousassignment.js in a text editor
  • Locate the line:
 var returnUrl = encodeURIComponent(currentUrl);
  • Change currentUrl to the app scheme uri (such as ms-powerpoint:// for Microsoft Powerpoint app)
  • Example:
var returnUrl = encodeURIComponent('ms-powerpoint://');
  • Save the file
  • Make sure you have a designated OneTouch authenticator for the flow.
  • Login to Configuration Manager and select Advanced-Authenticators HTTP
  • Locate the OneTouch authenticator.
  • Point to the custom template by changing the relevant parameter name (this can be different based on the type of OneTouch authenticator used. Please view the documentation for the authenticator to get the correct param name).
  • Example:
{
  "alias": "ot",
  "id": "myauthenticator",
  "name": "SAMLAnonymousAssignmentAuthenticator",
  "configuration": {
    "pipeID": "mypipe",
    "idpID": "myidp",
    "issuer": "Company ab",
    "allowLanguageChange": "true",
    "max_polls": "100",
    "poll_interval": "2000",
    "method_same_device_enabled": "true",
    "method_same_device_icon": "same-device.png",
    "method_other_device_enabled": "true",
    "method_other_device_icon": "other-device.png",
    "login_template_name": "custom_anonymousassignment.template",
    "assignment_template_name": "ot_auth_template.json"
  }
}

Other OneTouch authenticators

By default, OneTouch will switch back to the system web browser app (Safari on iOS, Chrome on Android).

To use OneTouch app-switching from a non-default app, follow these steps:

  • On the PhenixID server, copy <phenixid_server_root>/mods/com.phenixidentity~auth-http~<version>/templates/onetouchpoll.template. Name the copy custom_onetouchpoll.template.
  • Open custom_onetouchpoll.template in a texteditor.
  • Locate this part:
    {{#enable_ot}}
               
    // Open local OT and return to same page on completion
               
    window.location.replace('phxidpush://start?return_url=' + encodeURIComponent(window.location.href) + '&origin_url=' + encodeURIComponent(window.location.href));
               
    {{/enable_ot}}
  • Change window.location.href to the app scheme uri (such as ms-powerpoint:// for Microsoft Powerpoint app)
    {{#enable_ot}}

           // Open local OT and return to same page on completion

           window.location.replace('phxidpush://start?return_url=' + encodeURIComponent('ms-powerpoint://') + '&origin_url=' + encodeURIComponent('ms-powerpoint://'));

           {{/enable_ot}}

  • Save the file
  • Make sure you have a designated OneTouch authenticator for the flow.
  • Login to Configuration Manager and select Advanced-Authenticators HTTP
  • Locate the OneTouch authenticator.
  • Point to the custom poll template by changing the relevant parameter name (this can be different based on the type of OneTouch authenticator used. Please view the documentation for the authenticator to get the correct param name).
    Example:

{
  "id": "ot_01",
  "alias": "ot",
  "name": "AssignmentAuthenticator",
  "displayName": "PhenixID One Touch",
  "configuration": {
    "successURL": "/myapps/",
    "enableHoneypot": "false",
    "allowLanguageChange": "true",
    "notify": "true",
    "servicename": "PhenixID Demo MyApps",
    "ot_push_title": "Pending assignment(s)",
    "ot_push_message": "Open One Touch to view your assignment(s)",
    "poll_template_name": "custom_onetouchpoll.template"
  }
}