Getting started with PingID SDK using the sample demo app ("Moderno")

This document describes the steps to run the PingID SDK sample app (“Moderno”) in a PingOne account.

  1. General prerequisites
  2. Set up an authentication server using the PingID SDK sample authentication server
  3. Set up a mobile app using the PingID SDK sample code

General prerequisites:

  • A PingOne account. Complete the process at https://admin.pingone.com/web-portal/register.
  • Download the PingID SDK package from PingID downloads. The package contains:
    • The PingID SDK component for iOS and Android applications.
    • The PingID SDK sample customer server source code.
    • The PingID SDK sample customer server war file.
    • The PingID SDK demo app source code (Moderno).

Set up an authentication server using the PingID SDK sample authentication server

Software prerequisites

  • Mac OS X or Linux
  • Oracle Java 8: Download and install java 8 (Java SE Development Kit 8u121).
  • JCE for Java 8 (Java Cryptography Extension) to support extended encryption policy:
    • Download JCE.

    • Go to the Java installation on your machine, and in a terminal window enter the following command:

      cd $JAVA_HOME/jre/lib/security

    • Create backup files:

      sudo mkdir backup_security_jars

      sudo mv US_export_policy.jar backup_security_jars

      sudo mv local_policy.jar backup_security_jars

    • Extract the JCE files you downloaded, into the directory you’re in ($JAVA_HOME/jre/lib/security).

  • Apache-tomcat-7.0.7:
    • Download Tomcat 7.

    • Create a folder for Tomcat, and install it there, e.g. ~/dev/apache-tomcat-7.0.77

    • Go to Tomcat’s bin folder and set the execution permissions, e.g.:

      chmod +x *.sh

1. PingID SDK properties file and application configuration

  • Create the folder /env/moderno-props/

  • Download the pingidsdk.properties file from the admin web portal, and copy it to /env/moderno-props/.

  • Create an application in the admin web portal: Applications > PingID SDK Applications > + Add application.

    Copy the application ID, for the next step.

  • Add a new line to the pingidsdk.properties file:

    app_id=<application_id_from_PingOne_portal>

2. Deploy the PingIDSdkDemoServer application:

2a. Deploy the PingIDSdkDemoServer application to Tomcat

  • Extract the customer-server.war from the Server Sample Code folder of the PingID SDK zip package that you downloaded earlier.

  • Copy the customer-server.war to your Tomcat webapps folder, e.g.:

    cp customer-server.war ~/dev/apache-tomcat-7.0.73/webapps/.

2b. Build the PingIDSdkDemoServer application from sources

If you want to build the PingIDSdkDemoServer application from the sources, you should first install Apache Maven (3.2.2), and then download and build the PingIDSdkDemoServer application.

  1. Install Apache Maven:

    • Download Apache Maven (3.2.2).

    • Extract the zipped file into the ~/dev/apache-maven-x.x.x folder

    • Add Maven to the search path: export PATH=~/dev/apache-maven-x.x.x/bin:$PATH

    • Set the M2_HOME environment variable:

      • Create a new /etc/launchd.conf file OR edit the existing file.

      • Add the following line to /etc/launchd.conf:

        setenv M2_HOME /Users/<<your user name>>/dev/apache-maven-x.x.x

        (x.x.x=Maven version you downloaded)

    • Add Maven to the path:

      • Create the file /etc/paths.d/m2_bin

      • Add the line:

        ~/dev/apache-maven-x.x.x/bin

    • To make sure Maven uses the correct java version, create a script that sets JAVA_HOME:

      • In the terminal enter “echo $JAVA_HOME” and copy the returned path.

      • Launch the AppleScript Editor, and enter the following lines:

        do shell script "launchctl setenv JAVA_HOME /Library/Java/JavaVirtualMachines/jdk1.7.0_80.jdk/Contents/Home/"

        do shell script "launchctl setenv M2_HOME ~/dev/apache-maven-x.x.x"

      • Save as file format: Application.

      • Open System Preferences > Users & Groups > Login Items tab > add your new application.

  2. Download and build the PingIDSdkDemoServer application from sources:

    • Unzip the PingIDSdkDemoServer-x.x.zip.

    • Open a terminal and go to the folder of the unzipped file.

      cd CustomerServer  
      mvn clean package  
      cd target
      `
      • Rename the file sample-customer-server-*.war to customer-server.war::

        mv sample-customer-server-*.war customer-server.war

      • Copy customer-server.war to the Tomcat webapps folder, eg.:

        cp customer-server.war ~/dev/apache-tomcat-7.0.73/webapps/

2c. Run Tomcat

Set up a mobile app using the PingID SDK sample code

Prerequisites

  1. Prepare the iOS push messaging certificates and Android FCM credentials:

    If you intend to use push messaging in your app, verify that you have your push configuration information:

  2. Make sure that you have the following prerequisites:

  • The applicationId you used in the server side integration (above).
  • The PingID SDK properties file.
  • The application configuration.

Configure iOS push messaging certificates and Android FCM credentials:

  • iOS Remote Notification:
    • When configuring your PingID SDK application in the PingOne admin web portal, you should upload your Apple iOS Push Services Certificate. Find it under “Connect to your application” in the Application Configuration Page in the PingOne admin web portal.
  • Google cloud messaging:
    • When configuring your PingID SDK application in the PingOne admin web portal, et your FCM/GCM Sender Id and secret key. Find it under “Connect to your application” in the Application Configuration Page in the PingOne admin web portal.

IDE integration

  1. PingID SDK Demo Application iOS - IDE integration:

    PingID SDK supports the following software versions:

    • Xcode 8 and above.
    • iOS 8.0 and above.

    In the example app make sure that you change the following settings in Constants.m:

    kCustomerServerUrl  
    kAppID

    to your customer server URL,and the ApplicationID, which you retrieved from the PingOne admin web portal. Add the PingID SDK component into your existing project.

    • In your Project Navigator, click on your target, and drag PingID.framework to Embedded Binaries.

    • Check the Copy items if needed checkbox.

    • PingID SDK uses location, if it is available. Make sure to ask for location permissions in your app code before the following call:

      + (void)initAppID:(nonnull NSString *)appID error:(NSError * _Nullable * _Nullable)error;

      If your app doesn’t use location, you will need to add the NSLocationWhenInUseUsageDescription key to your info.plist with a short description, implement CLLocationManager, and ask for location permissions.

    • Setup the Run Script phase.

      • Make sure that the Run Script phase is after the Embed Frameworks phase.

      • Select your application’s Xcode project, then your application target, and then select Build Phases, click “+”, and then New Run Script Build Phase.

      • Paste the following line into the body of the Run Script Build Phase:

        bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/PingID.framework/strip-frameworks.sh"

  2. PingID SDK Demo Application Android - IDE integration: IDE integration: Add the SDK into your existing project.

    We recommend the following software versions:

    • Gradle version 2.14.1 or later.
    • Gradle Android plugin version 2.2.2 or later.
    • Make sure that the Android SDK installed contains SDK version 25. The PingID SDK component is compiled using SDK version 25 (7.1.1) with build tools version 25. We recommend you use these settings.
    • Configure your project with gradle: http://developer.android.com/sdk/installing/studio-build.html.

    • Make the following changes to your build.gradle files in order to add the PingID SDK component dependency:

      • Open your top level build.gradle file, to add the PingID SDK component as a dependency. Add the following lines to the allprojects node under the repositories node:

        flatDir {
                     dirs 'libs'
                 }
      • Create a libs folder inside your module’s folder. Copy the PingID SDK component file PingID_SDK.aar into it.

      • Inside the module or modules using the PingID SDK component - add the following dependency:

        {
               compile(name: 'PingID_SDK', ext: 'aar')
         }
      • As the PingID SDK component is loaded locally, you’ll have to add the PingID SDK component’s dependencies manually in order to be able to compile and run it. Add these dependencies under the PingID SDK component dependency:

        compile 'org.slf4j:slf4j-api:1.7.7'
        compile 'com.github.tony19:logback-android-core:1.1.1-6'
        compile('com.github.tony19:logback-android-classic:1.1.1-6') {
            exclude group: 'com.google.android', module: 'android'
        }
        compile 'com.nimbusds:nimbus-jose-jwt:4.11'
        compile 'com.google.code.gson:gson:2.6.2'
        compile 'commons-codec:commons-codec:1.5'
        compile 'com.madgag:sc-light-jdk15on:1.47.0.3'
        compile 'com.madgag:scprov-jdk15on:1.47.0.3'
        compile 'com.google.android.gms:play-services-base:10.2.1'
        compile 'com.google.firebase:firebase-messaging:10.2.1'
    • Open the file AppPreferences.java, and update the following variables:

      DEFAULT_CUSTOMER_SERVER_BASE_URL = <Current demo customer server>

      DEFAULT_APP_ID = <Your PingID SDK app Id>

      DEFAULT_PUSH_SENDER_ID = <Your FCM/GCM sender Id>

    • Connect a device and run the app.