Technical Guide

The EPM Plugin requires configuration of its overall settings and individual actions, as well as the triggering of intents to start, stop, and reconfigure the plugin, clearing of app data on logout, and a custom script to enable the credential capture to happen.

epmPluginConfig

The configuration for EPM resides within the Launcher configuration JSON.

Field	Description
settings	object Stores key-value pairs that determine behavior common to all actions on the device - including what the actions' overlays will look like and whether they will use shared keys or not.
actions	array List of action objects that define the specific credentials and automated button taps that will occur for each application.

settings

Field	Description
overlayHeightPct	int Percentage of the screen that the overlay card will cover, as a whole number.
cardColor	string Hex code for the color of the overlay card.
disableContextMenu	boolean If set to true, will automatically dismiss the context menu that is displayed on long-press in Microsoft Authenticator and Edge apps. Introduced in Launcher version 3.23.0. Default is false.

actions

Field	Description
actionId	string Descriptive name to identify the action that will be triggered.
credentialId	string Defines whether or not the action should apply credentials captured by the custom script. Based on the custom_script JS, your BlueFletch rep can tell you what string to set (e.g. "bf_creds" or "azure_creds"). An invalid descriptive string such as "#nocreds-teams#" can indicate that the action will not use captured credentials for that action.
packages	string Package name of the application for which the action applies. Currently only supports one package name.
pageText	array List of strings that identify application page on which to apply the action. Pages are identified by the presence of the selected strings. Suggestion: Pick a string or partial string that is unique to each page.
usernameHints	array List of strings that identify an application's username text fields by the placeholder hint texts present in them.
passwordHints	array List of strings that identify an application's password text fields by the placeholder hint texts present in them.
submitButtonHints	array List of strings that identify submit buttons that will be tapped by the button's text. Usually submit buttons follow username or password entry.
textButtonHints	array List of strings that identify non-submit buttons that will be tapped by the button's text. Usually text buttons are for proceeding through welcome screens that do not require credentials.
haltOnErrorHints	array List of strings that if encountered on the screen will trigger the action to pause and allow the user to resume control. Including strings or partial strings of errors in this array prevents an action from getting stuck in a loop of failed attempts.

Other Configuration Requirements

Supported Intents

Three intent actions are required to enable, disable, and reconfigure the EPM plugin.

com.bluefletch.ems.epm.ACTION_RDR_ENABLE should be triggered to run on every login to enable EPM.

com.bluefletch.ems.epm.ACTION_RDR_DISABLE should be triggered to run on every logout to disable EPM when it is not needed.

com.bluefletch.ems.epm.ACTION_CONFIG_RELOAD should be triggered to run regularly outside of the session to periodically reload the configuration to the EPM plugin. Some custom intent timings to consider using: preLogin, postLogout, cradle, or uncradle.

For example:

    "intents": {
        "login": [
            {
                "typeIntent": "b",
                "action": "com.bluefletch.ems.epm.ACTION_RDR_ENABLE",
                "package": "com.bluefletch.ems.epm"
            }
        ],
        "logout": [
            {
                "typeIntent": "b",
                "action": "com.bluefletch.ems.epm.ACTION_RDR_DISABLE",
                "package": "com.bluefletch.ems.epm"
            }
        ],
        "postLogout": [
            {
                "typeIntent": "b",
                "action": "com.bluefletch.ems.epm.ACTION_CONFIG_RELOAD",
                "package": "com.bluefletch.ems.epm"
            }
        ]
    }

Clear App Data on Logout Settings

To remove the credentials used to login to native apps on logout, Launcher must be allowed to clear app data on the the authentication module and all applications that have used EPM to login during a session. The EPM package itself should not have its data cleared, however, to retain its Accessibility permission.

  "settings": {
    ...
    "clearAppDataOnLogout": "true",
    "clearAppDataIncludeList": "<the Auth package and all packages that have been logged into with EPM>",
    "clearAppDataExcludeList": "com.bluefletch.ems.epm,<other packages that should not be cleared on logout for business purposes>"
  }

Custom Script Path with Asset

A custom Javascript file provided by BlueFletch is required to capture credentials when logging in through the BlueFletch Browser (for example, using an Auth 4 OIDC application). BlueFletch recommends defining the custom script path using Assets Manager.

    "assets": {
        "custom_script": "<local file path or hosted URL for script>"
    },
    "browser": {
        ...
        "customScriptPath": "assets:custom_script"
    }

Full Example

...    
    "settings": {
        ...
        "clearAppDataOnLogout": "true",
        "clearAppDataIncludeList": "com.android.chrome,com.microsoft.teams,com.microsoft.office.outlook,com.microsoft.skydrive,com.bluefletch.ems.auth",
        "clearAppDataExcludeList": "com.bluefletch.ems.epm"
    },
    "intents": {
        "login": [
            {
                "typeIntent": "b",
                "action": "com.bluefletch.ems.epm.ACTION_RDR_ENABLE",
                "package": "com.bluefletch.ems.epm"
            }
        ],
        "logout": [
            {
                "typeIntent": "b",
                "action": "com.bluefletch.ems.epm.ACTION_RDR_DISABLE",
                "package": "com.bluefletch.ems.epm"
            }
        ],
        "postLogout": [
            {
                "typeIntent": "b",
                "action": "com.bluefletch.ems.epm.ACTION_CONFIG_RELOAD",
                "package": "com.bluefletch.ems.epm"
            }
        ]
    },
        "assets": {
        "custom_script": "https://examplefilehosting.com/customScript.js"
    },
    "browser": {
        ...
        "customScriptPath": "assets:custom_script"
    },        
    "epmPluginConfig": {
        "settings": {
            "overlayHeightPct": 100
        },
        "actions": [
            {
                "actionId" : "Teams App Action",
                "credentialId": "azure_creds",
                "packages": "com.microsoft.teams",
                "pageText": [
                  "connected and organized",
                  "continue to Teams",
                  "Enter password"
                ],
                "usernameHints": [
                    "Enter email or phone number"
                ],
                "passwordHints": [
                  "Enter password",
                  "Password",
                  "Enter the password for"
                ],
                "textButtonHints": [],
                "submitButtonHints": [
                    "Get started", "Next", "Sign in"
                ],
                "haltOnErrorHints": [
                    "Please enter valid sign-in info",
                    "Enter an email or phone number",
                    "Your account or password is incorrect",
                    "Couldn't find your Google Account",
                    "Please enter the characters you see in the image above",
                    "Enter a password",
                    "Please enter your password",
                    "Sorry, but we're having trouble",
                    "AADST",
                    "Enter a code",
                    "We texted your phone",
                    "Please enter the characters you see",
                    "2-Step Verification",
                    "Approve sign in request"
                ]
            },
            {
                "actionId" : "Teams Welcome Screens Action",
                "credentialId": "#nocreds-teams#",
                "packages": "com.microsoft.teams",
                "pageText" : [
                    "Use this account",
                    "Collaborate with others",
                    "Chat with your colleagues",
                    "Have meetings and calls",
                    "Your privacy option"
                ],
                "usernameHints": [],
                "passwordHints": [],
                "textButtonHints": [],
                "submitButtonHints": [
                  "Create or use another account", "Next", "Got it"
                ],
                "haltOnErrorHints": [
                    "Please enter valid sign-in info",
                    "Enter an email or phone number",
                    "Your account or password is incorrect",
                    "Couldn't find your Google Account",
                    "Please enter the characters you see in the image above",
                    "Enter a password",
                    "Please enter your password",
                    "Sorry, but we're having trouble",
                    "AADST",
                    "Enter a code",
                    "We texted your phone",
                    "Please enter the characters you see",
                    "2-Step Verification",
                    "Approve sign in request"
                ]
            },
            {
              "actionId" : "Outlook App Action",
              "credentialId": "azure_creds",
              "packages": "com.microsoft.office.outlook",
              "pageText" : [
                  "Add account",
                  "Accounts found",
                  "Enter password"
              ],
              "usernameHints": [
                  "Enter your email"
              ],
              "passwordHints": [
                  "Password"
              ],
              "textButtonHints": [],
              "submitButtonHints": [
                  "Sign in",
                  "CONTINUE"
              ],
              "haltOnErrorHints": [
                  "Please enter valid sign-in info",
                  "Enter an email or phone number",
                  "Your account or password is incorrect",
                  "Couldn't find your Google Account",
                  "Please enter the characters you see in the image above",
                  "Enter a password",
                  "Please enter your password",
                  "Sorry, but we're having trouble",
                  "AADST",
                  "Enter a code",
                  "We texted your phone",
                  "Please enter the characters you see",
                  "2-Step Verification",
                  "Approve sign in request"
              ]
            },
            {
              "actionId" : "Outlook Welcome Screens Action",
              "credentialId": "#nocreds-outlook#",
              "packages": "com.microsoft.office.outlook",
              "pageText" : [
                  "Would you like to add another account?",
                  "Stay in the flow"
              ],
              "usernameHints": [],
              "passwordHints": [],
              "textButtonHints": [],
              "submitButtonHints": [
                  "MAYBE LATER",
                  "GOT IT"
              ],
              "haltOnErrorHints": [
                  "Please enter valid sign-in info",
                  "Enter an email or phone number",
                  "Your account or password is incorrect",
                  "Couldn't find your Google Account",
                  "Please enter the characters you see in the image above",
                  "Enter a password",
                  "Please enter your password",
                  "Sorry, but we're having trouble",
                  "AADST",
                  "Enter a code",
                  "We texted your phone",
                  "Please enter the characters you see",
                  "2-Step Verification",
                  "Approve sign in request"
              ]
            },
            {
              "actionId" : "OneDrive App Action",
              "credentialId": "azure_creds",
              "packages": "com.microsoft.skydrive",
              "pageText" : [
                  "Welcome to OneDrive",
                  "Protect your files and access",
                  "Enter your work, school or personal",
                  "Enter password"
              ],
              "usernameHints": [
                  "Email or phone"
              ],
              "passwordHints": [
                  "Password"
              ],
              "textButtonHints": [],
              "submitButtonHints": [
                  "SIGN IN",
                  "Sign in"
              ],
              "haltOnErrorHints": [
                  "Please enter valid sign-in info",
                  "Enter an email or phone number",
                  "Your account or password is incorrect",
                  "Couldn't find your Google Account",
                  "Please enter the characters you see in the image above",
                  "Enter a password",
                  "Please enter your password",
                  "Sorry, but we're having trouble",
                  "AADST",
                  "Enter a code",
                  "We texted your phone",
                  "Please enter the characters you see",
                  "2-Step Verification",
                  "Approve sign in request"
              ]
            },
            {
                "actionId" : "Generic Chrome Azure Login",
                "credentialId": "azure_creds",
                "packages": "com.android.chrome",
                "pageText": [
                    "login.microsoftonline.com"
                ],
                "usernameHints": [
                    "Email or phone",
                    "Email, phone, or Skype",
                    "[e-mail]"
                ],
                "passwordHints": [
                    "Password",
                    "Enter your password"
                ],
                "submitButtonHints": [
                    "Next",
                    "Sign in",
                    "Yes",
                    "Use without an account",
                    "Accept & continue",
                    "Allow"
                ],
                "haltOnErrorHints": [
                    "Pick an account",
                    "Enter an email or phone number",
                    "Your account or password is incorrect",
                    "Couldn’t find your Google Account",
                    "Please enter the characters you see in the image above",
                    "Enter a password",
                    "Please enter your password",
                    "Sorry, but we're having trouble",
                    "AADST",
                    "Enter a code",
                    "Enter code",
                    "We texted your phone",
                    "Please enter the characters you see",
                    "2-Step Verification",
                    "Approve sign in request"
                ]
            },
            {
                "actionId" : "Initial Chrome Prompts",
                "credentialId": "#nocreds-chrome#",
                "packages": "com.android.chrome",
                "pageText" : [
                    "Welcome to Chrome"
                ],
                "usernameValue" : "null",
                "passwordValue" : "null",
                "textButtonHints" : [ ],
                "submitButtonHints": [ 
                    "Use without an account","Accept & continue"
                ]
            }
        ]
    },