Asset Amway ID Native Login 1.0.4

Downloadable Asset:

com.alticor.nativelogin.zip

Developer Guide Documentation:

login_marketplace_component_template.docx

Asset Version:

1.0.4

Asset Description:

The Kony Native login component is used to display the Amway ID login page in the native app and authenticate the user using the built-in Kony OAuth capabilities. The component features a built-in user native interface that can be used to launch the login process. This interface can be customized (background image, colors, labels, etc.) as needed or can be entirely disabled if a custom experience is needed.

Details:

<ul>
<li>Bug Fixes</li>
<li>Documentation update</li>
</ul>
 1 Overview

The Kony Native login component is used to display the Amway ID login page in the native app and authenticate the user using the built-in Kony OAuth capabilities.  The component has the following capabilities:

<ul>
<li>·Biometrics - Biometric authentication is simply the process of verifying your identity using your measurements or other unique characteristics of your body, then logging you in a service, an app, a device, and so on. The component allows for using biometrics such as TouchID, FaceID, and Fingerprint recognition.  It supports the following two modes via configuration:

<ul>
<li>USER PREFERENCE - biometrics can be enabled or disabled by the app user.</li>
<li>NONE - biometrics are not enabled for the app. In this case, the user has to login using credentials every time.</li>
</ul>
</li>
<li>Highly Configurable UI - the component can be configured to use the built-in user interface, or the user interface can be completely disabled if a custom UI is needed.</li>
</ul>

The component features a built-in user native interface that can be used to launch the login process.  This interface can be customized (background image, colors, labels, etc.) as needed or can be <a href="#WebLogin-disable-ui">entirely disabled</a> if a custom experience is needed.

2 Application Security

For enhanced security, Quantum provides strong application protection solutions by using anti-tampering mechanisms, White-Box Cryptography (WBC), Cryptography, and Encryption APIs, and also can secure network communications. Following are two methods you can use to enhance security in your application.

Note: In order to use this component and interface with Amway ID securely, your application is required to implement the following security protections. Failure to do so may result in vulnerabilities that could require your app to be shut down in production.

2.1 Public Key Pinning

SSL Pinning

SSL Pinning is the process of associating a host with their expected X509 certificate or a public key. Once a host's certificate or public key is known or identified, the certificate or public key is associated or 'pinned' to the host. This offers protection against certificate forgery.

To enable the Public Key Pinning feature for a Quantum Visualizer Application, For more information on, click <a href="https://docs.kony.com/konylibrary/visualizer/visualizer_user_guide/conte...

2.2 Protected Mode option

Applications built in Quantum Visualizer can use the additional security enhancements by building the application in the Protected Mode. Quantum Visualizer Platform code for iOS and Android is equipped with mechanisms that can protect your application by detecting attacks like tampering, swizzling, debugging, jailbreaking (iOS), rooting (Android), and information disclosure. Additional security mechanisms are provided through the use of White-Box Cryptography to protect application business logic and source code. Application reacts to the attack by exiting upon detecting attacks to prevent further attempts.

For more information on how to implement, please click <a href="https://docs.kony.com/konylibrary/visualizer/visualizer_user_guide/conte...

3 Getting Started with the AmwayID Login component

This is a Getting Started section for the AmwayID Login. It contains information about importing and running the component.

For information about the Dynamic Usage, Properties, Events, and APIs of the component, you can visit the Reference Section.

Before you start using the nativeLogin component, make sure that you meet all the requirements in the Prerequisites.

4 Prerequisites

<ul>
<li>A <a href="https://manage.kony.com/" target="_blank">Kony account</a></li>
<li>Kony Visualizer V8 SP4, or higher</li>
<li>Create a Client App at AmwayID</li>
<li>Create Identity Service</li>
</ul>

4.1 Source Code

The component source can be found at <a href="https://github.com/AmwayACS/AmwayIDNativeLogin">https://github.com/Amway...

4.2 Create Identity Service

The Kony framework has built-in support for authentication using OpenID Connect / OAuth2 which means that there is minimal code you need to write to support login into your application.

To do so, you need to configure an Identity Service, which will be used by the component to integrate with Amway ID via OpenID Connect.  Follow the steps below to configure the Kony framework.

Create a New Identity Service

Open the Configure Services tab and choose the Identity screen.  Click the Configure New button.

Enter a name for your identity service and select the Type of Identity dropdown.  In the dialog that opens, choose OAuth 2.0.

This will open a screen allowing you to provide the needed configuration details.  Follow the instructions in the table below.

Provider Details

Grant Type: Use Password

Authorize Endpoint: Varies per environment.  Can be generated with the <a href="http://jira.amway.com:8444/display/GIW/OIDC+Application+Tool">OIDC Application Tool</a>.

Token Endpoint: Varies per environment.  Can be generated with the <a href="http://jira.amway.com:8444/display/GIW/OIDC+Application+Tool">OIDC Application Tool</a>.

Callback URL: This will be set by the Kony framework for your application.

Scope: This will depend on what data you need in your tokens and what services your app will use.  See <a href="http://jira.amway.com:8444/display/GIW/Token+Enrichment">Token Enrichment</a>.

Logout URL: Varies per environment.  See <a href="http://jira.amway.com:8444/display/GIW/Logout">Logout</a>.

Revoke URL: Varies per environment.  Can be generated with the <a href="http://jira.amway.com:8444/display/GIW/OIDC+Application+Tool">OIDC Application Tool</a>.

Client Details

Client ID: The value will be provided to you by the Amway ID Team

Client Secret: The value will be provided to you by the Amway ID Team

Advanced

Choose the Additional Parameters and click on "Add" button.

Define amw_clientapp,amw_cancelredirect params as per below.

Note: amw_cancelredirect URL has to be whitelisted as part of your client app policy.

4.3 Identity Service Configuration

You need to configure an Identity session configuration that will be used for session idle time out and adding security attributes as part of identity response. Follow the steps below to configure in the Kony framework.

Open the Configure Services tab and choose the Identity screen.  Click the Service Configuration button.

This will open a screen allowing you to provide the needed configuration details.  Follow the instructions in the table below.

Provide idle session time and maximum session durations as per your requirement and select the checkbox for Allow Clients to Access Secure Attributes.

4.4 Android

<ul>
<li>USE_FINGERPRINT.</li>
<li>Deep link URL schema</li>
</ul>

Refer to the <a href="#_Overview">Configuring Native Settings (Android) </a>section for more information.

4.5 iOS

<ul>
<li>Camera Permissions.</li>
<li>Face ID Permissions</li>
</ul>

Refer to the <a href="#_Providing_Camera_and">Configuring Native Settings (iOS)</a> section for more information.

After you make sure that you meet all the prerequisites, you can expand any of the following drop downs to get details about each step of getting started with the Component.

5 Importing the Component

Before you start importing the component to Kony Visualizer, you must download the component from the Amway Marketplace website. You can import the marketplace components only into the apps that are of the Kony Reference Architecture type.

To import the AmwayID Login component, do the following:

<ol>
<li>Open your app project in Kony Visualizer.</li>
<li>On the File menu, point to Import, and click Component to Library. The Open dialog appears.</li>
<li>Navigate to the location where you downloaded the component (zip file) on your computer, select the component, and click Open. After Visualizer downloads the component, it opens a window that asks you to enter the metadata for the component.</li>
</ol>

Enter a Library Name, a Collection Name, and a Description if you require one.

<ul>
<li>Library Name - A Library contains component collections and skins. The Library Name specifies the library that you want to import the component into. If the library does not exist, Visualizer will create a new one. 
As an example, let us name the Library as AmwayID.</li>
<li>Collection Name - A collection contains multiple components. The Collection Name specifies the collection that you want to import the component into. If the collection does not exist in the specified library, Visualizer will create a new one. 
As an example, let us name the Collection as Login.</li>
<li>Component Name - This name specifies the display name you want to use for the component in Visualizer. 
By default, the component name is com.alticor.NativeLogin .</li>
<li>After you import the component, you can drag and drop it from the Collection Library onto your form.</li>
<li>Save the form now.</li>
</ul>

After you add the component to a form, you need to configure the native settings of your project. You can refer to the following sections for more information.

5.1 Configuring Component Properties

To configure the Component, you need to perform the following tasks.

<ol>
<li>App Config</li>
</ol>

Property: Amway ID URL 
Syntax: baseURL 
Type: Text 
Description: Specifies the URL which is used for Forgot password

Property: Cancel Redirect URL 
Syntax: cancelRedirectURL 
Type: Text 
Description: Specifies app deep link URL for redirection when user clicks on the Cancel button.

Property: Is Request From Logout 
Syntax: isReqFromLogout 
Type: Boolean 
Description: Need to set if the request is coming from the Logout page.

Property: App Default Language 
Syntax: defaultLocale 
Type: List 
Description: Define App default language, if your Language is not available in the list, please add in the list and select at component code.

Property: Country 
Syntax: country 
Type: List 
Description: Define App default Country from List, if your country is not available in the list, please add in the list and select at component code.

Property: Biometric Login 
Syntax: biometricLoginType 
Type: List 
Description: Define the Biometric login required for your app or not. See section#1 for more information.

Property: Custom Login UI 
Syntax: customLoginUI 
Type: Boolean 
Description: Configure whether you are using default AmwayID native login or your own custom UI

Property: Enable Forgot Password 
Syntax: forgotPwdVisibility 
Type: Boolean 
Description: The app would like to show 'Forgot Password' option or not.

Property: Enable Privacy &Terms of Use 
Syntax: privacyAndTermsVisibility 
Type: Boolean 
Description: The app would like to show the 'Privacy & Security' and 'Terms of Use' option or not.

2. Identity Config

Property: Identity Service Name 
Syntax: identityServiceID 
Type: Text 
Description: Specifies the identity service name which we have defined in Fabric server for our app.

Property: Client App Name 
Syntax: clientApp 
Type: Text 
Description: Specifies the client app name which we have defined in OAuth policy for our app.

Property: Enable Refresh Token 
Syntax: refreshToken 
Type: Boolean 
Description: Use Refresh Token for sub sequent logins if the token is valid without providing user credentials again. See section#1 for more information.

3. UI Config

Property: Display Login Toggle 
Syntax: loginToggleIsVisible 
Type: Boolean 
Description: Specifies the if you have multiple login buttons based on your app requirement.

Property: Login ID Type (Tab1) 
Syntax: loginBtn1Name 
Type: Text 
Description: Specifies the Name of Tab1 from above.

Property: Login ID Type (Tab2) 
Syntax: loginBtn2Name 
Type: Text 
Description: Specifies the Name of Tab2 from above.

Property: Loading Indicator Skin 
Syntax: loadingIndSkin 
Type: Text 
Description: Assign loading indicator skin as per your app requirement else it will take the default AmwayID login loading indicator

Property: Request from Logout Action 
Syntax: isReqFromLogout 
Type: Boolean 
Description: This can be set dynamically in the controller to define the request is coming from Logout action or its initial request.

5.2 Configuring Native Settings (iOS)

To configure the native settings for iOS, you need to perform the following tasks.

<ul>
<li>Provide Camera and Face ID Permissions</li>
</ul>

5.2.1.1 Providing Camera and Face ID Permissions

<ol>
<li>From the Project explorer, go to Assets.</li>
<li>Expand Media, right-click Common, and then select Resource Location. 
A file explorer window opens.</li>
<li>Open the infoplist_configuration.json file with a text editor or a code editor.</li>
<li>At the end of the file, type the given code . You can change the description based on your preference.</li>
</ol>

"NSCameraUsageDescription" : "AmwayID uses Camera to enable Face ID for this app.",

"NSFaceIDUsageDescription" : "AmwayID uses your Face ID to authenticate the app.",

5. Save the file.

5.3 <a href="javascript:void(0);">Configuring Native Settings (Android)</a>

To configure the native settings for Android, follow the given steps.

<ol>
<li>From the left navigation menu, click Project Settings.</li>
</ol>

<ol>
<li>In the Project Settings window, go to Native → Android.</li>
<li>Scroll down to the Manifest Permissions, Tags and Gradle Build Entries section, and then select the USE_FINGERPRINT, select the permission from the left panel and click Add >.</li>
</ol>

5.4 <a href="javascript:void(0);">Building and Running your app</a>

After performing all the above steps, you can perform either of the following tasks:

Build and Publish your app (Visualizer Enterprise)

For more information, you can refer to the <a href="http://docs.kony.com/konylibrary/visualizer/visualizer_user_guide/Defaul... target="_blank">Building and Viewing an Application</a> section of the Visualizer User Guide.

6 Biometric Support

Using biometrics for consumer-facing mobile application authentication is an emerging enterprise imperative that delivers both ease of use and improved security. Biometrics can help organizations overcome the limitations of usernames and passwords and improve user experience and security. Recent advances in the mobile technology landscape, such as the widespread production of smartphones with fingerprint sensors, make biometric authentication an appealing alternative to usernames and passwords.

The Amway ID component supports the use of biometrics including Face ID, Touch ID, and Fingerprint.  When enabling using the Amway ID component UI there are 2 modes for biometric support:

Mode: None

Description: The app does not allow the use of biometrics to enter the app.

Mode: USER PREFERENCE

Description: The user can decide whether to enable biometrics to enter the app.

When choosing User Preference, this will enable an option on the component's user interface that allows the user to choose whether to require biometrics to login into the app.  This selection is dynamic based on the capabilities of the device - if Face ID is supported, then "Enable Face ID" is displayed in the field.  If Touch ID is supported, "Enable Touch ID" is displayed. if Fingerprint is supported, then "Enable Fingerprint" is displayed in the field.

The biometric pop-up will appear on the screen and takes user consent to enable Biometric on the device when the user login successfully.

Once the user enables Biometric Login then subsequent calls it automatically authenticates the user with FaceID/TouchID/Fingerprint.

7 APIs

7.1 Callback Events

From the Properties panel, navigate to the Actions tab. The Actions tab contains a set of events.

You need to associate actions with the following events listed below.

onLoginSuccess

Description: Invoked when the component successfully Logged in the user.

Syntax: onLoginSuccess()

Example: this.view.NativeLogin.onLoginSuccess = this.onLoginSuccess;

onLoginFailure

Description: Invoked when the user login failed.

Syntax: onLoginFailure()

Example: this.view.NativeLogin.onLoginFailure = this.onLoginFailure;

Request from Logout Action

if(!kony.sdk.isNullOrUndefined(eventobject) && !kony.sdk.isNullOrUndefined(eventobject.isReqFromLogout)){

this.view.NativeLogin.isReqFromLogout = eventobject.isReqFromLogout;

}

8 Custom UI

The component can be configured to use the built-in user interface, or the user interface can be completely disabled if a custom UI is needed.

This interface can be customized (background image, colors, labels, etc.) as needed or can be <a href="#WebLogin-disable-ui">entirely disabled</a> if a custom experience is needed.

In this section we will discuss how to customize the User interface and how to integrate with Native Login Component.

8.1 Disable Native Login Component

After importing the component into form, turn off the native login component visibility to implement Customized User Interface.

Click on Component --> Properties Tab --> Look -- > Visible

You need to design your own UI and depends on your requirement you have to implement below methods:

8.2 Enabling Custom UI on Login Component

Turn on Custom UI to implement the Customized UI in the app as below. And for detailed property configurations please see section#<a href="#_Configuring_Component_Properties">Configuring Component Properties</a>

8.3 Custom UI API

8.3.1 displayErrorMessageOnCustomUI

This method has to be mapped to display Error message from login.

Syntax: this.view.NativeLogin.displayErrorMessageOnCustomUI = this.displayErrorMessageOnCustomUI;

8.3.2    saveCustomUIBiometricData

Need to write a logic to prepare user credentials to persist in keychain, since its customized UI and AmwayID login component doesn’t know the fields to map while saving user credentials in Keychain.

Syntax: this.view.NativeLogin.saveCustomUIBiometricData = this.saveCustomUIBiometricData;

8.3.3 showCustomUIBiometricOption

Display the enable/disable Biometric Login for application upon Login success.

Syntax: this.view.NativeLogin.showCustomUIBiometricOption = this.showCustomUIBiometricOption;

8.3.4 showNativeLoginUI

we need to map the method,  If in case you are trying to leverage existing feature in default Native Login which is using in app browser.

Example: Forgot Password.

Syntax: this.view.NativeLogin.showNativeLoginUI = this.showNativeLoginUI;

8.3.5 dismissNativeLoginUI

This method need to be mapped when we enable native login screen (Ex: section#9.4)

Syntax:  this.view.NativeLogin.dismissNativeLoginUI = this.dismissNativeLoginUI;

8.3.6 enableCustomUIBiometricLogin

Write a logic to enable fields to be enable while Biometric login on Custom UI. Its completely Application level decision to decide which fields should be enable and disable.

Syntax:  this.view.NativeLogin.enableCustomUIBiometricLogin = this.enableCustomUIBiometricLogin;

8.3.7 resetLoginForm

Need to reset the login form whenever or wherever required.

Syntax: this.view.NativeLogin.resetCustomLoginForm = this.resetLoginForm;

8.3.8 setDeviceBiometricType

Identify the device supported type by invoking Biometric API and set the labels accordingly while displaying the Biometric Login.

Syntax:  this.view.NativeLogin.customSetDeviceBiometricType = this.setDeviceBiometricType;

8.3.9 enableAndroidBiometricPopup

Display the Android Biometric popup with required fields when you invoke the Biometric login as Android platform doesn’t support native biometric UI same like iOS.

Syntax: this.view.NativeLogin.enableCustomAndroidBiometricPopup = this.enableAndroidBiometricPopup;

8.3.10 androidBiometricPopup

Need to write a logic to display Biometric popup for Android platform as the native OS will not support. Application has to come up with its own design and fields. Based on the Android Biometric Login status we need to enable disable specific fields.

Syntax: this.view.NativeLogin.displayAndroidPopup = this.androidBiometricPopup;

8.3.11 dismissAndroidPopup

Need to write a logic to dismiss the android popup after biometric login success/failure.

Syntax: this.view.NativeLogin.closeCustomAndroidPopup = this.dismissAndroidPopup;

A demo app with Customized UI has been implemented for better understand and implementation. Please find the complete code at <a href="https://github.com/AmwayACS/AmwayIDNativeLogin">https://github.com/Amway...

Custom Login Form ID : frmCustomLoginUI

9 External Links

External links will need to be added to the main application and will not be added to the Amway ID component. Documentation for links to Amway ID (create account etc.) can be found <a href="https://jira.amway.com:8444/display/GIW/Integrations">here</a>.

Please find the confluence link <a href="https://jira.amway.com:8444/display/GIW/Login+Component">here</a>

Supported App Types:

Supported Devices:

Supported Platforms:

Platform Version:

Asset Requirements:

Visualizer Enterprise