Installing and configuring the Persistent Mobile Foundation Application Center

Overview

You install the Application Center as part of the PMF installation. You can install it with one of the following methods:

  • Installation with Ant tasks
  • Manual installation

Optionally, you can create the database of your choice before you install PMF with the Application Center.
After you installed the Application Center in the web application server of your choice, you have additional configuration to do. For more information, see Configuring Application Center after installation below. If you chose a manual setup in the installer, see the documentation of the server of your choice.

Note: If you intend to install applications on iOS devices through the Application Center, you must first configure the Application Center server with SSL.

Optional creation of databases

If you want to activate the option to install the Application Center when you run the PMF installer, you need to have certain database access rights that entitle you to create the tables that are required by the Application Center. The database needs to be created before you start the PMF installer.

The following topics describe the procedure for the supported database management systems.

Jump to

Creating the DB2 database for PMF Application Center

During Persistent Mobile Foundation installation, the installer can create the Application Center database for you.

The installer can create the Application Center database for you if you enter the name and password of a user account on the database server that has the DB2 SYSADM or SYSCTRL privilege, and the account can be accessed through SSH. Otherwise, the database administrator can create the Application Center database for you. For more information, see the DB2 Solution user documentation.

When you manually create the database, you can replace the database name (here APPCNTR) and the password with a database name and password of your choosing.

Important: You can name your database and user differently, or set a different password, but ensure that you enter the appropriate database name, user name, and password correctly across the DB2 database setup. DB2 has a database name limit of 8 characters on all platforms, and has a user name and password length limit of 8 characters for UNIX and Linux systems, and 30 characters for Windows.

  1. Create a system user, for example, named wluser in a DB2 admin group such as DB2USERS, using the appropriate commands for your operating system. Give it a password, for example, wluser. If you want multiple instances of PMF to connect to the same database, use a different user name for each connection. Each database user has a separate default schema. For more information about database users, see the DB2 documentation and the documentation for your operating system.

  2. Open a DB2 command line processor, with a user that has SYSADM or SYSCTRL permissions:

    • On Windows systems, click Start → IBM DB2 → Command Line Processor
    • On Linux or UNIX systems, navigate to ~/sqllib/bin and enter ./db2.

    • Enter database manager and SQL statements similar to the following example to create the Application Center database, replacing the user name wluser with your chosen user names:

      CREATE DATABASE APPCNTR COLLATE USING SYSTEM PAGESIZE 32768
CONNECT TO APPCNTR
GRANT CONNECT ON DATABASE TO USER wluser
DISCONNECT APPCNTR
QUIT

  3. The installer can create the database tables and objects for Application Center in a specific schema. This allows you to use the same database for PMF Application Center and for a PMF server project. If the IMPLICIT_SCHEMA authority is granted to the user created in step 1 (the default in the database creation script in step 2), no further action is required. If the user does not have the IMPLICIT_SCHEMA authority, you need to create a SCHEMA for the Application Center database tables and objects.

Creating the MySQL database for PMF Application Center

During the PMF installation, the installer can create the PMF Application Center database for you.

The installer can create the database for you if you enter the name and password of the superuser account. For more information, see Securing the Initial MySQL Accounts on your MySQL database server. Your database administrator can also create the databases for you. When you manually create the database, you can replace the database name (here APPCNTR) and password with a database name and password of your choosing. Note that MySQL database names are case-sensitive on UNIX.

  1. Start the MySQL command-line tool.

  2. Enter the following commands:

    CREATE DATABASE APPCNTR CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON APPCNTR.* TO 'PMF'@'PMF-host' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON APPCNTR.* TO 'PMF'@'localhost' IDENTIFIED BY 'password';
FLUSH PRIVILEGES;

    Here, you need to replace PMF-host with the name of the host on which PMF runs.

Creating the Oracle database for PMF Application Center

During the installation, the installer can create the PMF Application Center database, except for the Oracle 12c database type, or the user and schema inside an existing database for you.

The installer can create the database, except for the Oracle 12c database type, or the user and schema inside an existing database if you enter the name and password of the Oracle administrator on the database server, and the account can be accessed through SSH. Otherwise, the database administrator can create the database or user and schema for you. When you manually create the database or user, you can use database names, user names, and a password of your choosing. Note that lowercase characters in Oracle user names can lead to trouble.

  1. If you do not already have a database named ORCL, use the Oracle Database Configuration Assistant (DBCA) and follow the steps in the wizard to create a new general-purpose database named ORCL:
    • Use global database name ORCL_your_domain, and system identifier (SID) ORCL.
    • On the Custom Scripts tab of the step Database Content, do not run the SQL scripts, because you must first create a user account.
    • On the Character Sets tab of the step Initialization Parameters, select Use Unicode (AL32UTF8) character set and UTF8 - Unicode 3.0 UTF-8 national character set.
    • Complete the procedure, accepting the default values.
  2. Create a database user either by using Oracle Database Control, or by using the Oracle SQLPlus command-line interpreter.
    • Using Oracle Database Control:
      • Connect as SYSDBA.
      • Go to the Users page: click Server, then Users in the Security section.
      • Create a user, for example, named APPCENTER. If you want multiple instances of Persistent PMF to connect to the same general-purpose database you created in step 1, use a different user name for each connection. Each database user has a separate default schema.
      • Assign the following attributes:
        • Profile: DEFAULT
        • Authentication: password
        • Default tablespace: USERS
        • Temporary tablespace: TEMP
        • Status: Unlocked
        • Add system privilege: CREATE SESSION
        • Add system privilege: CREATE SEQUENCE
        • Add system privilege: CREATE TABLE
        • Add quota: Unlimited for tablespace USERS

    • Using the Oracle SQLPlus command-line interpreter:
      The commands in the following example create a user named APPCENTER for the database:

        CONNECT SYSTEM/<SYSTEM_password>@ORCL
  CREATE USER APPCENTER IDENTIFIED BY password DEFAULT TABLESPACE USERS QUOTA UNLIMITED ON USERS;
  GRANT CREATE SESSION, CREATE SEQUENCE, CREATE TABLE TO APPCENTER;
  DISCONNECT;

      Note while using Oracle as database: If you are using same schema for both MFPADMIN & APPCENTER components, please check that, ‘OPEN_JPA_SEQUENCE_TABLE’ exists before installing MFPAdmin. If table exists, please delete it with below steps. Installation script should re-create it. <Add steps for executing delete table script present in our installer>

Jump to

Installing the Persistent Mobile Foundation Application Center with Ant tasks

Learn about the Ant tasks that you can use to install PMF Application Center.

Jump to

Creating and configuring the database for PMF Application Center with Ant tasks

If you did not manually create the database, you can use Ant tasks to create and configure your database for PMF Application Center. If your database already exists, you can perform only the configuration steps with Ant tasks.

Before you begin, make sure that a database management system (DBMS) is installed and running on a database server, which can be on the same computer, or a different one.

The Ant tasks for PMF Application Center are in the ApplicationCenter/configuration-samples directory of the PMF distribution.

If you want to start the Ant task from a computer where PMF is not installed, you must copy the following files to that computer:

  • The library pmf_install_dir/MobileFoundationServer/mfp-ant-deployer.jar
  • The directory that contains binary files of the aapt program, from the Android SDK platform-tools package: pmf_install_dir/ApplicationCenter/tools/android-sdk
  • The Ant sample files that are in pmf_install_dir/ApplicationCenter/configuration-samples

Note: The pmf_install_dir placeholder represents the directory where you installed PMF.

If you did not create your database manually, as described in Optional creation of databases, follow steps 1 to 3 below. If your database already exists, you must create only the database tables. Follow steps 4 to 7 below.

  1. Copy the sample Ant file that corresponds to your DBMS. The files for creating a database are named after the following pattern:

     create-appcenter-database-<dbms>.xml
  2. Edit the Ant file, and replace the placeholder values with the properties at the beginning of the file.

  3. Run the following commands to create the Application Center database:

     ant -f create-appcenter-database-<dbms>.xml databases

    If the database already exists, then you must create only the database tables by completing the following steps:

  4. Copy the sample Ant file that corresponds to both your application server, and your DBMS. The files for configuring an existing database are named after this pattern:

     configure-appcenter-<appServer>-<dbms>.xml
  5. Edit the Ant file, and replace the placeholder values with the properties at the beginning of the file.

  6. Run the following commands to configure the database:

     ant -f configure-appcenter-<appServer>-<dbms>.xml databases
  7. Save the Ant file. You might need it later to apply a fix pack, or perform an upgrade.

If you do not want to save the passwords, you can replace them by “****” (12 stars) for interactive prompting.

Deploying the Application Center Console and Services with Ant tasks

Use Ant tasks to deploy the Application Center Console and Services to an application server, and configure data sources, properties, and database drivers that are used by Application Center.

Before you begin,

  • Complete the procedure at Creating and configuring the database for Application Center with Ant tasks.

  • You must run the Ant task on the computer where the application server is installed. If you want to start the Ant task from a computer where PMF is not installed, you must copy the following files and directories to that computer:

    • The library pmf_install_dir/MobileFoundationServer/mfp-ant-deployer.jar
    • The web applications (WAR and EAR files) in mf_server_install_dir/ApplicationCenter/console
    • The directory that contains the binary files of the aapt program, from the Android SDK platform-tools package: pmf_install_dir/ApplicationCenter/tools/android-sdk
    • The Ant sample files that are in pmf_install_dir/ApplicationCenter/configuration-samples

Note: The  pmf_install_dir placeholder represents the directory where you installed PMF.

  1. Copy the Ant file that corresponds both to your application server, and your DBMS. The files for configuring Application Center are named after the following pattern:

     configure-appcenter-<appserver>-<dbms>.xml
  2. Edit the Ant file, and replace the placeholder values with the properties at the beginning of the file.

  3. Run the following command to deploy the Application Center Console and Services to an application server:

     ant -f configure-appcenter-<appserver>-<dbms>.xml install

    Note: With these Ant files, you can also do the following actions:

    • Uninstall Application Center, with the target uninstall.
    • Update Application Center with the target update, to apply a fix pack.
  4. Save the Ant file. You might need it later to apply a fix pack or perform an upgrade. If you do not want to save the passwords, you can replace them by “****” (12 stars) for interactive prompting.

  5. If you installed on WebSphere Application Server Liberty profile, or Apache Tomcat, check that the aapt program is executable for all users. If needed, you must set the proper user rights. For example, on UNIX / Linux systems:

     chmod a+x  pmf_install_dir/ApplicationCenter/tools/android-sdk/*/aapt*

Manually installing Application Center

A reconfiguration is necessary for the PMF to use a database or schema that is different from the one that was specified during its installation. This reconfiguration depends on the type of database and on the kind of application server.

On application servers other than Apache Tomcat, you can deploy Application Center from two WAR files or one EAR file.

Jump to

Configuring the DB2 database manually for Application Center

You configure the DB2 database manually by creating the database, creating the database tables, and then configuring the relevant application server to use this database setup.

  1. Create the database. This step is described in Creating the DB2 database for Application Center.
  2. Create the tables in the database. This step is described in Setting up your DB2 database manually for Application Center.
  3. Perform the application server-specific setup as the following list shows.

Jump to

Setting up your DB2 database manually for Application Center

Set up your DB2 database for Application Center by creating the database schema.

  1. Create a system user, PMF, in a DB2 admin group such as DB2USERS, by using the appropriate commands for your operating system. Give it the password PMF. For more information, see the DB2 documentation and the documentation for your operating system.

Important: You can name your user differently, or set a different password, but ensure that you enter the appropriate user name and password correctly across the DB2 database setup. DB2 has a user name and password length limit of 8 characters for UNIX and Linux systems, and 30 characters for Windows.

  1. Open a DB2 command line processor, with a user that has SYSADM or SYSCTRL permissions:
    • On Windows systems, click Start → IBM DB2 → Command Line Processor.
    • On Linux or UNIX systems, go to ~/sqllib/bin and enter ./db2.

  2. Enter the following database manager and SQL statements to create a database that is called APPCNTR:

    CREATE DATABASE APPCNTR COLLATE USING SYSTEM PAGESIZE 32768
CONNECT TO APPCNTR
GRANT CONNECT ON DATABASE TO USER PMF
QUIT

  3. Run DB2 with the following commands to create the APPCNTR tables, in a schema named APPSCHM (the name of the schema can be changed). This command can be run on an existing database that has a page size compatible with the one defined in step 3.

    db2 CONNECT TO APPCNTR
db2 SET CURRENT SCHEMA = 'APPSCHM'
db2 -vf  pmf_install_dir/ApplicationCenter/databases/create-appcenter-db2.sql -t
Configuring Liberty profile for DB2 manually for Application Center

You can set up and configure your DB2 database manually for Application Center with WebSphere Application Server Liberty profile.
Complete the DB2 Database Setup procedure before continuing.

  1. Add the DB2 JDBC driver JAR file to $LIBERTY_HOME/wlp/usr/shared/resources/db2.

    If that directory does not exist, create it. You can retrieve the file in one of two ways:

  2. Configure the data source in the $LIBERTY_HOME/wlp/usr/servers/PMFServer/server.xml file as follows:

    In this path, you can replace PMFServer by the name of your server.

    <library id="DB2Lib">
     <fileset dir="${shared.resource.dir}/db2" includes="*.jar"/>
</library>

<!-- Declare the PMF Application Center database. -->
<dataSource jndiName="jdbc/AppCenterDS" transactional="false">
   <jdbcDriver libraryRef="DB2Lib"/>
   <properties.db2.jcc databaseName="APPCNTR"  currentSchema="APPSCHM"
         serverName="db2server" portNumber="50000"
         user="PMF" password="PMF"/>
</dataSource>

    The PMF placeholder after user= is the name of the system user with CONNECT access to the APPCNTR database that you have previously created.

    The PMF placeholder after password= is this user’s password. If you have defined either a different user name, or a different password, or both, replace PMF accordingly. Also, replace db2server with the host name of your DB2 server (for example, localhost, if it is on the same computer).

    DB2 has a user name and password length limit of 8 characters for UNIX and Linux systems, and 30 characters for Windows.

  3. You can encrypt the database password with the securityUtility program in liberty_install_dir/bin.

Configuring Apache Tomcat for DB2 manually for Application Center

If you want to manually set up and configure your DB2 database for Application Center with Apache Tomcat server, use the following procedure.
Before you continue, complete the DB2 database setup procedure.

  1. Add the DB2 JDBC driver JAR file.

    You can retrieve this JAR file in one of the following ways:

    • Download it from DB2 JDBC Driver Versions.
    • Or fetch it from the directory db2_install_dir/java on the DB2 server) to $TOMCAT_HOME/lib.

  2. Prepare an XML statement that defines the data source, as shown in the following code example.

    <Resource auth="Container"
         driverClassName="com.ibm.db2.jcc.DB2Driver"
         name="jdbc/AppCenterDS"
         username="PMF"
         password="password"
         type="javax.sql.DataSource"
         url="jdbc:db2://server:50000/APPCNTR:currentSchema=APPSCHM;"/>

    The PMF parameter after username= is the name of the system user with “CONNECT” access to the APPCNTR database that you have previously created. The password parameter after password= is this user’s password. If you have defined either a different user name, or a different password, or both, replace these entries accordingly.

    DB2 enforces limits on the length of user names and passwords.

    • For UNIX and Linux systems: 8 characters
    • For Windows: 30 characters

  3. Insert this statement in the server.xml file, as indicated in Configuring Apache Tomcat for Application Center manually.

Configuring the Apache Derby database manually for Application Center

You configure the Apache Derby database manually by creating the database and database tables, and then configuring the relevant application server to use this database setup.

  1. Create the database and the tables within them. This step is described in Setting up your Apache Derby database manually for Application Center.
  2. Configure the application server to use this database setup. Go to one of the following topics.

Jump to

Setting up your Apache Derby database manually for Application Center

Set up your Apache Derby database for Application Center by creating the database schema.

  1. In the location where you want the database to be created, run ij.bat on Windows systems or ij.sh on UNIX and Linux systems.

    Note: The ij program is part of Apache Derby. If you do not already have it installed, you can download it from Apache Derby: Downloads.

    For supported versions of Apache Derby, see System requirements.
    The script displays ij version number.

  2. At the command prompt, enter the following commands:

    connect 'jdbc:derby:APPCNTR;user=APPCENTER;create=true';
run '< pmf_install_dir>/ApplicationCenter/databases/create-appcenter-derby.sql';
quit;
Configuring Liberty profile for Derby manually for Application Center

If you want to manually set up and configure your Apache Derby database for Application Center with WebSphere Application Server Liberty profile, use the following procedure. Complete the Apache Derby database setup procedure before continuing.

Configure the data source in the $LIBERTY_HOME/usr/servers/PMFServer/server.xml file (PMFServer may be replaced in this path by the name of your server) as follows:

<!-- Declare the jar files for Derby access through JDBC. -->
<library id="derbyLib">
  <fileset dir="C:/Drivers/derby" includes="derby.jar" />
</library>

<!-- Declare the PMF Application Center database. -->
<dataSource jndiName="jdbc/AppCenterDS" transactional="false" statementCacheSize="10">
  <jdbcDriver libraryRef="derbyLib"
              javax.sql.ConnectionPoolDataSource="org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource40"/>
  <properties.derby.embedded databaseName="DERBY_DATABASES_DIR/APPCNTR" user="APPCENTER"
                             shutdownDatabase="false" connectionAttributes="upgrade=true"/>
  <connectionManager connectionTimeout="180"
                     maxPoolSize="10" minPoolSize="1"
                     reapTime="180" maxIdleTime="1800"
                     agedTimeout="7200" purgePolicy="EntirePool"/>
</dataSource>
Configuring Apache Tomcat for Derby manually for Application Center

You can set up and configure your Apache Derby database manually for Application Center with the Apache Tomcat application server. Complete the Apache Derby database setup procedure before continuing.

  1. Add the Derby JAR file from pmf_install_dir/ApplicationCenter/tools/lib/derby.jar to the directory $TOMCAT_HOME/lib.

  2. Prepare an XML statement that defines the data source, as shown in the following code example.

    <Resource auth="Container"
         driverClassName="org.apache.derby.jdbc.EmbeddedDriver"
         name="jdbc/AppCenterDS"
         username="APPCENTER"
         password=""
         type="javax.sql.DataSource"
         url="jdbc:derby:DERBY_DATABASES_DIR/APPCNTR"/>
  3. Insert this statement in the server.xml file, as indicated in Configuring Apache Tomcat for Application Center manually.

Configuring the MySQL database manually for Application Center

You configure the MySQL database manually by creating the database, creating the database tables, and then configuring the relevant application server to use this database setup.

  1. Create the database. This step is described in Creating the MySQL database for Application Center.
  2. Create the tables in the database. This step is described in Setting up your MySQL database manually for Application Center.
  3. Perform the application server-specific setup as the following list shows.

Jump to

Setting up your MySQL database manually for Application Center

Complete the following procedure to set up your MySQL database.

  1. Create the database schema.
    • Run a MySQL command line client with the option -u root.
    • Enter the following commands:
    CREATE DATABASE APPCNTR CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON APPCNTR.* TO 'PMF'@'PMF-host'IDENTIFIED BY 'PMF';
GRANT ALL PRIVILEGES ON APPCNTR.* TO 'PMF'@'localhost' IDENTIFIED BY 'PMF';
FLUSH PRIVILEGES;

USE APPCNTR;
SOURCE  pmf_install_dir/ApplicationCenter/databases/create-appcenter-mysql.sql;

    Where PMF before the “at” sign (@) is the user name, PMF after IDENTIFIED BY is its password, and PMF-host is the name of the host on which Persistent Mobile Foundation runs.

  2. Add the following property to your MySQL option file: max_allowed_packet=256M.
    For more information about option files, see the MySQL documentation at MySQL.

  3. Add the following property to your MySQL option file: innodb_log_file_size = 250M
    For more information about the innodb_log_file_size property, see the MySQL documentation, section innodb_log_file_size.
Configuring Liberty profile for MySQL manually for Application Center

If you want to manually set up and configure your MySQL database for Application Center with WebSphere Application Server Liberty profile, use the following procedure. Complete the MySQL database setup procedure before continuing.

Note: MySQL in combination with WebSphere Application Server Liberty profile is not classified as a supported configuration.

  1. Add the MySQL JDBC driver JAR file to $LIBERTY_HOME/wlp/usr/shared/resources/mysql. If that directory does not exist, create it.

  2. Configure the data source in the $LIBERTY_HOME/usr/servers/PMFServer/server.xml file (PMFServer may be replaced in this path by the name of your server) as follows:

    <!-- Declare the jar files for MySQL access through JDBC. -->
<library id="MySQLLib">
   <fileset dir="${shared.resource.dir}/mysql" includes="*.jar"/>
</library>

<!-- Declare the PMF Application Center database. -->
<dataSource jndiName="jdbc/AppCenterDS" transactional="false">
   <jdbcDriver libraryRef="MySQLLib"/>
<properties databaseName="APPCNTR"
           serverName="mysqlserver" portNumber="3306"
           user="PMF" password="password"/>
</dataSource>

    Where PMF after user= is the user name, password after password= is this user’s password, and mysqlserver is the host name of your MySQL server (for example, localhost, if it is on the same machine).

  3. You can encrypt the database password with the securityUtility program in <liberty_install_dir>/bin.
Configuring Apache Tomcat for MySQL manually for Application Center

If you want to manually set up and configure your MySQL database for Application Center with the Apache Tomcat server, use the following procedure. Complete the MySQL database setup procedure before continuing.

  1. Add the MySQL Connector/J JAR file to the $TOMCAT_HOME/lib directory.
  2. Prepare an XML statement that defines the data source, as shown in the following code example. Insert this statement in the server.xml file, as indicated in Configuring Apache Tomcat for Application Center manually.
<Resource name="jdbc/AppCenterDS"
            auth="Container"
            type="javax.sql.DataSource"
            maxActive="100"
            maxIdle="30"
            maxWait="10000"
            username="PMF"
            password="password"
            driverClassName="com.mysql.jdbc.Driver"
            url="jdbc:mysql://server:3306/APPCNTR"/>

Configuring the Oracle database manually for Application Center

You configure the Oracle database manually by creating the database, creating the database tables, and then configuring the relevant application server to use this database setup.

  1. Create the database. This step is described in Creating the Oracle database for Application Center.
  2. Create the tables in the database. This step is described in Setting up your Oracle database manually for Application Center.
  3. Perform the application server-specific setup as the following list shows.

Jump to

Setting up your Oracle database manually for Application Center

Complete the following procedure to set up your Oracle database.

  1. Ensure that you have at least one Oracle database.

    In many Oracle installations, the default database has the SID (name) ORCL. For best results, specify Unicode (AL32UTF8) as the character set of the database.

    If the Oracle installation is on a UNIX or Linux computer, make sure that the database is started next time the Oracle installation is restarted. To this effect, make sure that the line in /etc/oratab that corresponds to the database ends with a Y, not with an N.

  2. Create the user APPCENTER, either by using Oracle Database Control, or by using the Oracle SQLPlus command-line interpreter.
    • To create the user for the Application Center database/schema, by using Oracle Database Control, proceed as follows:
      • Connect as SYSDBA.
      • Go to the Users page.
      • Click Server, then Users in the Security section.
      • Create a user, named APPCENTER with the following attributes:
      Profile: DEFAULT
Authentication: password
Default tablespace: USERS
Temporary tablespace: TEMP
Status: Unlocked
Add system privilege: CREATE SESSION
Add system privilege: CREATE SEQUENCE
Add system privilege: CREATE TABLE
Add quota: Unlimited for tablespace USERS

    • To create the user by using Oracle SQLPlus, enter the following commands:

      CONNECT SYSTEM/<SYSTEM_password>@ORCL
CREATE USER APPCENTER IDENTIFIED BY password DEFAULT TABLESPACE USERS QUOTA UNLIMITED ON USERS;
GRANT CREATE SESSION, CREATE SEQUENCE, CREATE TABLE TO APPCENTER;
DISCONNECT;
  3. Create the tables for the Application Center database:
    • Using the Oracle SQLPlus command-line interpreter, create the tables for the Application Center database by running the create-appcenter-oracle.sql file:
    CONNECT APPCENTER/APPCENTER_password@ORCL
@pmf_install_dir/ApplicationCenter/databases/create-appcenter-oracle.sql
DISCONNECT;
  4. Download and configure the Oracle JDBC driver:
Configuring Liberty profile for Oracle manually for Application Center

You can set up and configure your Oracle database manually for Application Center with WebSphere Application Server Liberty profile by adding the JAR file of the Oracle JDBC driver. Before continuing, set up the Oracle database.

  1. Add the JAR file of the Oracle JDBC driver to $LIBERTY_HOME/wlp/usr/shared/resources/oracle. If that directory does not exist, create it.

  2. If you are using JNDI, configure the data sources in the $LIBERTY_HOME/wlp/usr/servers/MobileFoundationServer/server.xml file as shown in the following JNDI code example:

    Note: In this path, you can replace MobileFoundationServer with the name of your server.

    <!-- Declare the jar files for Oracle access through JDBC. -->
<library id="OracleLib">
   <fileset dir="${shared.resource.dir}/oracle" includes="*.jar"/>
</library>

<!-- Declare the PMF Application Center database. -->
<dataSource jndiName="jdbc/AppCenterDS" transactional="false">
   <jdbcDriver libraryRef="OracleLib"/>
   <properties.oracle driverType="thin"
                      serverName="oserver" portNumber="1521"
                      databaseName="ORCL"
                      user="APPCENTER" password="APPCENTER_password"/>
</dataSource>

    Where:

    • APPCENTER after user= is the user name,
    • APPCENTER_password after password= is this user’s password, and
    • oserver is the host name of your Oracle server (for example, localhost if it is on the same machine).

    Note: For more information on how to connect the Liberty server to the Oracle database with a service name, or with a URL, see the WebSphere Application Server Liberty Core 8.5.5 documentation, section properties.oracle.

  3. You can encrypt the database password with the securityUtility program in liberty_install_dir/bin.
Configuring Apache Tomcat for Oracle manually for Application Center

If you want to manually set up and configure your Oracle database for Application Center with the Apache Tomcat server, use the following procedure. Complete the Oracle database setup procedure before continuing.

  1. Add the Oracle JDBC driver JAR file to the directory $TOMCAT_HOME/lib.
  2. Prepare an XML statement that defines the data source, as shown in the following code example. Insert this statement in the server.xml file, as indicated in Configuring Apache Tomcat for Application Center manually
<Resource name="jdbc/AppCenterDS"
        auth="Container"
        type="javax.sql.DataSource"
        driverClassName="oracle.jdbc.driver.OracleDriver"
        url="jdbc:oracle:thin:@oserver:1521:ORCL"
        username="APPCENTER"
        password="APPCENTER_password"/>

Where APPCENTER after username= is the name of the system user with “CONNECT” access to the APPCNTR database that you have previously created, and APPCENTER_password after password= is this user’s password. If you have defined either a different user name, or a different password, or both, replace these values accordingly.

Deploying the Application Center WAR files and configuring the application server manually

The procedure to manually deploy the Application Center WAR files manually to an application server depends on the type of application server being configured.
These manual instructions assume that you are familiar with your application server.

Note: Using the PMF installer to install Application Center is more reliable than installing manually, and should be used whenever possible.

If you prefer to use the manual process, follow these steps to configure your application server for Application Center. You must deploy the appcenterconsole.war and applicationcenter.war files to your Application Center. The files are located in pmf_install_dir/ApplicationCenter/console.

Jump to

Configuring the Liberty profile for Application Center manually

To configure WebSphere Application Server Liberty profile manually for Application Center, you must modify the server.xml file.
In addition to modifications for the databases that are described in Manually installing Application Center, you must make the following modifications to the server.xml file.

  1. Ensure that the <featureManager> element contains at least the following <feature> elements:

    <feature>jdbc-4.0</feature>
<feature>appSecurity-2.0</feature>
<feature>servlet-3.0</feature>
<feature>usr:MFPDecoderFeature-1.0</feature>

  2. Add the following declarations for Application Center:

    <!-- The directory with binaries of the 'aapt' program, from the Android SDK's
      platform-tools package. -->
<jndiEntry jndiName="android.aapt.dir" value="pmf_install_dir/ApplicationCenter/tools/android-sdk"/>
<!-- Declare the Application Center Console application. -->
<application id="appcenterconsole"
              name="appcenterconsole"
              location="appcenterconsole.war"
              type="war">
   <application-bnd>
     <security-role name="appcenteradmin">
       <group name="appcentergroup"/>
     </security-role>
   </application-bnd>
   <classloader delegation="parentLast">
   </classloader>
</application>

<!-- Declare the PMF Application Center Services application. -->
<application id="applicationcenter"
              name="applicationcenter"
              location="applicationcenter.war"
              type="war">
   <application-bnd>
     <security-role name="appcenteradmin">
       <group name="appcentergroup"/>
     </security-role>
   </application-bnd>
   <classloader delegation="parentLast">           
   </classloader>
</application>

<!-- Declare the user registry for the PMF Application Center. -->
<basicRegistry id="applicationcenter-registry"
                realm="ApplicationCenter">
   <!-- The users defined here are members of group "appcentergroup",
        thus have role "appcenteradmin", and can therefore perform
        administrative tasks through the Application Center Console. -->
   <user name="appcenteradmin" password="admin"/>
   <user name="demo" password="demo"/>
   <group name="appcentergroup">
     <member name="appcenteradmin"/>
     <member name="demo"/>
   </group>
</basicRegistry>

    The groups and users that are defined in the basicRegistry are example logins that you can use to test Application Center. Similarly, the groups that are defined in the <security-role name="appcenteradmin"> for the Application Center console and the Application Center service are examples. For more information about how to modify these groups, see Configuring the Java EE security roles on WebSphere Application Server Liberty profile.

  3. If the database is Oracle, add the commonLibraryRef attribute to the class loader of the Application Center service application.

    ...
<classloader delegation="parentLast"  commonLibraryRef="OracleLib">
...

    The name of the library reference (OracleLib in this example) must be the ID of the library that contains the JDBC JAR file. This ID is declared in the procedure that is documented in Configuring Liberty profile for Oracle manually for Application Center.

  4. Copy the Application Center WAR files to your Liberty server.

    • On UNIX and Linux systems:

      mkdir -p LIBERTY_HOME/wlp/usr/servers/server_name/apps
cp  pmf_install_dir/ApplicationCenter/console/*.war LIBERTY_HOME/wlp/usr/servers/server_name/apps/

    • On Windows systems:

      mmkdir LIBERTY_HOME\wlp\usr\servers\server_name\apps
copy /B  pmf_install_dir\ApplicationCenter\console\appcenterconsole.war
LIBERTY_HOME\wlp\usr\servers\server_name\apps\appcenterconsole.war
copy /B  pmf_install_dir\ApplicationCenter\console\applicationcenter.war
LIBERTY_HOME\wlp\usr\servers\server_name\apps\applicationcenter.war
  5. Copy the password decoder user feature.

    • On UNIX and Linux systems:

      mkdir -p LIBERTY_HOME/wlp/usr/extension/lib/features
cp  pmf_install_dir/features/com.ibm.websphere.crypto_1.0.0.jar LIBERTY_HOME/wlp/usr/extension/lib/
cp  pmf_install_dir/features/MFPDecoderFeature-1.0.mf LIBERTY_HOME/wlp/usr/extension/lib/features/

    • On Windows systems:

      mkdir LIBERTY_HOME\wlp\usr\extension\lib
copy /B  pmf_install_dir\features\com.ibm.websphere.crypto_1.0.0.jar  
LIBERTY_HOME\wlp\usr\extension\lib\com.ibm.websphere.crypto_1.0.0.jar
mkdir LIBERTY_HOME\wlp\usr\extension\lib\features
copy /B  pmf_install_dir\features\MFPDecoderFeature-1.0.mf  
LIBERTY_HOME\wlp\usr\extension\lib\features\MFPDecoderFeature-1.0.mf
  6. Start the Liberty server.
Configuring Apache Tomcat for Application Center manually

To configure Apache Tomcat for Application Center manually, you must copy JAR and WAR files to Tomcat, add database drivers, edit the server.xml file, and then start Tomcat.

  1. Add the database drivers to the Tomcat lib directory. See the instructions for the appropriate DBMS in Manually installing PMF Application Center.
  2. Edit tomcat_install_dir/conf/server.xml.
    • Uncomment the following element, which is initially commented out: <Valve className="org.apache.catalina.authenticator.SingleSignOn" />.

    • Declare the PMF Application Center console and services applications and a user registry:

      <!-- Declare the PMF Application Center Console application. -->
<Context path="/appcenterconsole" docBase="appcenterconsole">

    <!-- Define the AppCenter services endpoint in order for the AppCenter
         console to be able to invoke the REST service.
         You need to enable this property if the server is behind a reverse
         proxy or if the context root of the Application Center Services
         application is different from '/applicationcenter'. -->
    <!-- <Environment name="ibm.appcenter.services.endpoint"
                      value="http://proxy-host:proxy-port/applicationcenter"
                      type="java.lang.String" override="false"/>
    -->

</Context>

<!-- Declare the PMF Application Center Services application. -->
<Context path="/applicationcenter" docBase="applicationcenter">
    <!-- The directory with binaries of the 'aapt' program, from
         the Android SDK's platform-tools package. -->
    <Environment name="android.aapt.dir"
                 value="pmf_install_dir/ApplicationCenter/tools/android-sdk"
                 type="java.lang.String" override="false"/>
    <!-- The protocol of the application resources URI.
         This property is optional. It is only needed if the protocol
         of the external and internal URI are different. -->
    <!-- <Environment name="ibm.appcenter.proxy.protocol"
                      value="http" type="java.lang.String" override="false"/>
    -->

    <!-- The host name of the application resources URI. -->
    <!-- <Environment name="ibm.appcenter.proxy.host"
                      value="proxy-host"
                      type="java.lang.String" override="false"/>
    -->

    <!-- The port of the application resources URI.
         This property is optional. -->
    <!-- <Environment name="ibm.appcenter.proxy.port"
                      value="proxy-port"
                      type="java.lang.Integer" override="false"/> -->

    <!-- Declare the PMF Application Center Services database. -->
    <!-- <Resource name="jdbc/AppCenterDS" type="javax.sql.DataSource" ... -->

</Context>

<!-- Declare the user registry for the PMF Application Center.
       The MemoryRealm recognizes the users defined in conf/tomcat-users.xml.
       For other choices, see Apache Tomcat's "Realm Configuration HOW-TO"
       http://tomcat.apache.org/tomcat-9.0-doc/realm-howto.html . -->
<Realm className="org.apache.catalina.realm.MemoryRealm"/>

    Where you fill in the <Resource> element as described in one of the sections:

  3. Copy the Application Center WAR files to Tomcat.

    • On UNIX and Linux systems:

      cp pmf_install_dir/ApplicationCenter/console/*.war TOMCAT_HOME/webapps/

    • On Windows systems:

      copy /B pmf_install_dir\ApplicationCenter\console\appcenterconsole.war tomcat_install_dir\webapps\appcenterconsole.war
copy /B pmf_install_dir\ApplicationCenter\console\applicationcenter.war tomcat_install_dir\webapps\applicationcenter.war
  4. Start Tomcat.

Deploying the PMF Application Center EAR file and configuring the application server manually

As an alternative to the PMF installer procedure, you can use a manual procedure to deploy the PMF Application Center EAR file and configure your WebSphere application server manually. These manual instructions assume that you are familiar with your application server.

The procedure to deploy the PMF Application Center EAR file manually to an application server depends on the type of application server. Manual deployment is supported only for WebSphere Application Server Liberty profile.

For manual procedure, deploy the appcentercenter.ear file, which you can find in the pmf_install_dir/ApplicationCenter/console directory.

Configuring the Liberty profile for PMF Application Center manually

After you deploy the Application Center EAR file, to configure WebSphere Application Server Liberty profile manually for PMF Application Center, you must modify the server.xml file.

In addition to modifications for the databases that are described in Manually installing PMF Application Center, you must make the following modifications to the server.xml file.

  1. Ensure that the <featureManager> element contains at least the following <feature> elements:

    <feature>jdbc-4.0</feature>
<feature>appSecurity-2.0</feature>
<feature>servlet-3.0</feature>
<feature>usr:MFPDecoderFeature-1.0</feature>

  2. Add the following declarations for PMF Application Center:

    <!-- The directory with binaries of the 'aapt' program, from the Android SDK's platform-tools package. -->
<jndiEntry jndiName="android.aapt.dir" value="pmf_install_dir/ApplicationCenter/tools/android-sdk"/>

<!-- Declare the PMF Application Center application. -->
<application id="applicationcenter"
              name="applicationcenter"
              location="applicationcenter.ear"
              type="ear">
   <application-bnd>
     <security-role name="appcenteradmin">
       <group name="appcentergroup"/>
     </security-role>
   </application-bnd>
   <classloader delegation="parentLast">           
   </classloader>
</application>

<!-- Declare the user registry for the PMF Application Center. -->
<basicRegistry id="applicationcenter-registry"
                realm="ApplicationCenter">
   <!-- The users defined here are members of group "appcentergroup",
        thus have role "appcenteradmin", and can therefore perform
        administrative tasks through the Application Center Console. -->
   <user name="appcenteradmin" password="admin"/>
   <user name="demo" password="demo"/>
   <group name="appcentergroup">
     <member name="appcenteradmin"/>
     <member name="demo"/>
   </group>
</basicRegistry>

    The groups and users that are defined in the basicRegistry element are example logins, which you can use to test Application Center. Similarly, the groups that are defined in the <security-role name="appcenteradmin"> element are examples. For more information about how to modify these groups, see Configuring the Java EE security roles on WebSphere Application Server Liberty profile.

  3. If the database is Oracle, add the commonLibraryRef attribute to the class loader of the Application Center application.

    ...
<classloader delegation="parentLast"  commonLibraryRef="OracleLib">
...

    The name of the library reference (OracleLib in this example) must be the ID of the library that contains the JDBC JAR file. This ID is declared in the procedure that is documented in Configuring Liberty profile for Oracle manually for PMF Application Center.

  4. Copy the Application Center EAR files to your Liberty server.

    • On UNIX and Linux systems:

       mkdir -p LIBERTY_HOME/wlp/usr/servers/server_name/apps
 cp pmf_install_dir/ApplicationCenter/console/*.ear LIBERTY_HOME/wlp/usr/servers/server_name/apps/

    • On Windows systems:

       mkdir LIBERTY_HOME\wlp\usr\servers\server_name\apps
 copy /B pmf_install_dir\ApplicationCenter\console\applicationcenter.ear
 LIBERTY_HOME\wlp\usr\servers\server_name\apps\applicationcenter.ear
  5. Copy the password decoder user feature.

    • On UNIX and Linux systems:

      mkdir -p LIBERTY_HOME/wlp/usr/extension/lib/features
cp pmf_install_dir/features/com.ibm.websphere.crypto_1.0.0.jar LIBERTY_HOME/wlp/usr/extension/lib/
cp pmf_install_dir/features/MFPDecoderFeature-1.0.mf LIBERTY_HOME/wlp/usr/extension/lib/features/

    • On Windows systems:

      mkdir LIBERTY_HOME\wlp\usr\extension\lib
copy /B pmf_install_dir\features\com.ibm.websphere.crypto_1.0.0.jar  
LIBERTY_HOME\wlp\usr\extension\lib\com.ibm.websphere.crypto_1.0.0.jar
mkdir LIBERTY_HOME\wlp\usr\extension\lib\features
copy /B pmf_install_dir\features\MFPDecoderFeature-1.0.mf  
LIBERTY_HOME\wlp\usr\extension\lib\features\MFPDecoderFeature-1.0.mf
  6. Start the Liberty server.

Configuring Application Center after installation

After you install Application Center in the web application server that you designated, you have additional configuration to do.

Jump to

Configuring user authentication for Application Center

You configure user authentication and choose an authentication method. The configuration procedure depends on the web application server that you use. Application Center requires user authentication.

You must perform some configuration after the installer deploys Application Center web applications in the web application server. Application Center has two Java™ Platform, Enterprise Edition (Java EE) security roles defined:

  • The appcenteruser role that represents an ordinary user of Application Center who can install mobile applications from the catalog to a mobile device belonging to that user.
  • The appcenteradmin role that represents a user who can perform administrative tasks through the Application Center console.

You must map the roles to the corresponding sets of users.

Java EE security roles in Application Center

If you choose to use an authentication method through a user repository such as LDAP, you can configure Application Center so that you can use users and groups with the user repository to define the Access Control List (ACL) of Application Center. This procedure is conditioned by the type and version of the web application server that you use. See Managing users with LDAP for information about LDAP used with Application Center.

After you configure authentication of the users of Application Center, which includes configuring LDAP if you plan to use it, you can, if necessary, define the endpoint of the application resources. You must then build the Application Center mobile client. The mobile client is used to install applications on mobile devices. See Preparations for using the mobile client for how to build the Application Center mobile client.

Jump to

Configuring the Java EE security roles on WebSphere Application Server Liberty profile

Configure the Java™ EE security roles of the Application Center and the data source in the server.xml file.

To configure the security roles, you must edit the server.xml file. In the <application-bnd> element of each <application> element, create two <security-role> elements. One <security-role> element is for the appcenteruser role and the other is for the appcenteradmin role. Map the roles to the appropriate user group name appcenterusergroup or appcenteradmingroup. These groups are defined through the <basicRegistry> element. You can customize this element or replace it entirely with an <ldapRegistry> element or a <safRegistry> element.

Then, to maintain good response times with a large number of installed applications, for example with 80 applications, you should configure a connection pool for the Application Center database.

  1. Edit the server.xml file. For example:

    <security-role name="appcenteradmin">
   <group name="appcenteradmingroup"/>
</security-role>
<security-role name="appcenteruser">
   <group name="appcenterusergroup"/>
</security-role>

    You must include this example in the following location:

    • If you deployed WAR files, in the <application-bnd> element of each <application> element: the appcenterconsole and applicationcenter applications.
    • If you deployed an EAR file, in the <application-bnd> element of the applicationcenter application.

    Replace the <security-role> elements that have been created during installation for test purposes.

    <basicRegistry id="appcenter">
   <user name="admin" password="admin"/>
   <user name="guest" password="guest"/>
   <user name="demo" password="demo"/>
   <group name="appcenterusergroup">
     <member name="guest"/>
     <member name="demo"/>
   </group>
   <group name="appcenteradmingroup">
     <member name="admin" id="admin"/>
   </group>
</basicRegistry>

    This example shows a definition of users and groups in the basicRegistry of WebSphere Application Server Liberty. For more information about configuring a user registry for WebSphere Application Server Liberty profile, see Configuring a user registry for the Liberty profile.

  2. Edit the server.xml file to define the AppCenterPool size.

    <connectionManager id="AppCenterPool" minPoolSize="10" maxPoolSize="40"/>

  3. In the <dataSource> element, define a reference to the connection manager:

    <dataSource id="APPCNTR" jndiName="jdbc/AppCenterDS" connectionManagerRef="AppCenterPool">
...
</dataSource>
Configuring the Java EE security roles on Apache Tomcat

You must configure the Java™ EE security roles for the Application Center on the Apache Tomcat web application server.

  1. In the Apache Tomcat web application server, you configure the roles of appcenteruser and appcenteradmin in the conf/tomcat-users.xml file. The installation creates the following users:

    <user username="appcenteradmin" password="admin" roles="appcenteradmin"/>
<user username="demo" password="demo" roles="appcenteradmin"/>
<user username="guest" password="guest" roles="appcenteradmin"/>

  2. You can define the set of users as described in the Apache Tomcat documentation, Realm Configuration HOW-TO.

Managing users with LDAP

Use the Lightweight Directory Access Protocol (LDAP) registry to manage users.

LDAP is a way to centralize the user management for multiple web applications in an LDAP Server that maintains a user registry. It can be used instead of specifying one by one the users for the security roles appcenteradmin and appcenteruser.

If you plan to use an LDAP registry with the Application Center, you must configure your WebSphere Application Server or your Apache Tomcat server to use an LDAP registry to authenticate users.

In addition to authentication of users, configuring the Application Center for LDAP also enables you to use LDAP to define the users and groups who can install mobile applications through the Application Center. The means of defining these users and groups is the Access Control List (ACL).

Jump to

LDAP with WebSphere Application Server V8.x

LDAP authentication is based on the federated repository configuration. ACL management configuration of the Application Center uses the Virtual Member Manager API.

You must configure LDAP based on the federated repository configuration. The stand-alone LDAP registry is not supported.

Several different repositories, LDAP and non-LDAP, can be configured in the federated repository.

For information about configuring federated repositories, see the WebSphere Application Server V8.0 user documentation or the WebSphere Application Server V8.5 user documentation, depending on your version.

Configuration of the Application Center for ACL management with LDAP

Some configuration details of ACL management are specific to the Application Center, because it uses the Virtual Member Manager (VMM) API.

The Application Center refers to these VMM attributes for users:

  • uid represents the user login name.
  • sn represents the full name of the user.
  • For groups, the Application Center refers only to the VMM attribute cn.
LDAP with Liberty profile

Use LDAP to authenticate users and to define the users and groups who can install mobile applications with the Application Center by using the JNDI environment.

Using LDAP with Liberty profile requires you to configure LDAP authentication and LDAP ACL management.

Configuring LDAP authentication for the Liberty profile

You can configure LDAP authentication of users and groups in the server.xml file by defining an LDAP registry or, since WebSphere Application Server Liberty profile V8.5.5, a federated registry that uses several LDAP registries. Then, you map users and groups to Application Center roles. The mapping configuration is the same for LDAP authentication and basic authentication.

  1. To open the server.xml descriptor file, enter {server.config.dir}/server.xml

  2. Insert one or several LDAP registry definitions after the <httpEndpoint> element. Example for the LDAP registry:

    <ldapRegistry baseDN="o=ibm.com" host="employees.com" id="Employees"
               ldapType="IBM Tivoli Directory Server" port="389" realm="AppCenterLdap"
               recursiveSearch="true">
   <idsFilters
       groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames))) " id="Employees"
       userFilter="(&amp;(emailAddress=%v)(objectclass=ibmPerson))"
       groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember"
       userIdMap="*:emailAddress"/>
</ldapRegistry>

    For information about the parameters that are used in this example, see the WebSphere Application Server V8.5 user documentation.

  3. Insert a security role definition after each Application Center application definition.

    • If you deployed WAR files: applicationcenter and appcenterconsole
    • If you deployed an EAR file: applicationcenter

    Group names unique within LDAP
    This sample code shows how to use the group names ldapGroupForAppcenteruser and ldapGroupForAppcenteradmin when they exist and are unique within LDAP.

    <application-bnd>
      <security-role name="appcenteruser" id="appcenteruser">
        <group name="ldapGroupForAppcenteruser" />
      </security-role>
      <security-role name="appcenteradmin" id="appcenteradmin">
        <group name="ldapGroupForAppcenteradmin" />
      </security-role>
</application-bnd>

    Group names not unique within LDAP
    This sample code shows how to code the mapping when the group names are not unique within LDAP. The groups must be specified with the access-id attribute. The access-id attribute must refer to the realm name that is used to specify the LDAP realm. In this sample code, the realm name is AppCenterLdap. The remainder of the access-id attribute specifies one of the LDAP groups named ldapGroup in a way that makes it unique.

    <application-bnd>
      <security-role name="appcenteruser" id="appcenteruser">
        <group name="ldapGroup"
               id="ldapGroup"
               access-id="group:AppCenterLdap/CN=ldapGroup,OU=myorg,
                          DC=mydomain,DC=AD,DC=myco,DC=com"/>
      </security-role>
      ...
</application-bnd>

    If applicable, use similar code to map the appcenteradmin role.

Configuring LDAP ACL management (Liberty profile)

You enable ACL management after you configure LDAP and map users and groups to Application Center roles. Only the simple type of LDAP authentication is supported.

To be able to define JNDI entries, the following feature must be defined in the server.xml file:

<feature>jndi-1.0</feature>

Add an entry for each property in the <server> section of the server.xml file. This entry should have the following syntax:

<jndiEntry jndiName="JNDI_property_name" value="property_value"/>

Where:

  • JNDI_property_name is the name of the property you are adding.
  • property_value is the value of the property you are adding.
Property Description
ibm.appcenter.ldap.active Set to true to enable LDAP; set to false to disable LDAP.
ibm.appcenter.ldap.federated.active Since WebSphere Application Server Liberty profile V8.5.5: set to true to enable use of the federated registry; set to false to disable use of the federated registry, which is the default setting.
ibm.appcenter.ldap.connectionURL LDAP connection URL.
ibm.appcenter.ldap.user.base Search base of users.
ibm.appcenter.ldap.user.loginName LDAP login attribute.
ibm.appcenter.ldap.user.displayName LDAP attribute for the user name to be displayed, for example, a person’s full name.
ibm.appcenter.ldap.group.base Search base of groups.
ibm.appcenter.ldap.group.name LDAP attribute for the group name.
ibm.appcenter.ldap.group.uniquemember LDAP attribute that identifies the members of a group.
ibm.appcenter.ldap.user.groupmembership LDAP attribute that identifies the groups to which a user belongs.
ibm.appcenter.ldap.group.nesting Management of nested groups: if nested groups are not managed, set the value to false.
ibm.appcenter.ldap.user.filter LDAP user search filter for the attribute of user login name. Use %v as the placeholder for the login name attribute. This property is only required when LDAP users and groups are defined in the same subtree; that is, when the properties ibm.appcenter.ldap.user.base and ibm.appcenter.ldap.group.base have the same value.
ibm.appcenter.ldap.displayName.filter LDAP user search filter for the attribute of user display name. Use %v as the placeholder for the display name attribute. This property is only required when LDAP users and groups are defined in the same subtree; that is, when the properties ibm.appcenter.ldap.user.base and ibm.appcenter.ldap.group.base have the same value.
ibm.appcenter.ldap.group.filter LDAP group search filter. Use %v as the placeholder for the group attribute. This property is only required when LDAP users and groups are defined in the same subtree; that is, when the properties ibm.appcenter.ldap.user.base and ibm.appcenter.ldap.group.base have the same value.
ibm.appcenter.ldap.security.sasl The value of the security authentication mechanism when the LDAP external SASL authentication mechanism is required to bind to the LDAP server. The value depends on the LDAP server; usually, it is set to “EXTERNAL”.
ibm.appcenter.ldap.security.binddn Property that identifies the distinguished name of the user permitted to search the LDAP directory. Use this property only if security binding is required.
ibm.appcenter.ldap.security.bindpwd Property that identifies the password of the user who is allowed to search the LDAP directory. Use this property only if security binding is required. The password can be encoded with the “Liberty profile securityUtility” tool. Run the tool and then set the value of this property to the encoded password generated by the tool. The supported encoding types are xor and aes. Edit the Liberty profile server.xml file to check whether the classloader is enabled to load the JAR file that decodes the password.
ibm.appcenter.ldap.cache.expiration.seconds elay in seconds before the LDAP cache expires. If no value is entered, the default value is 86400, which is equal to 24 hours. Changes to users and groups on the LDAP server become visible to the Application Center after a delay, which is specified by ibm.appcenter.ldap.cache.expiration.seconds. The Application Center maintains a cache of LDAP data and the changes only become visible after the cache expires. By default, the delay is 24 hours. If you do not want to wait for this delay to expire after changes to users or groups, you can call this command to clear the cache of LDAP data: acdeploytool.sh -clearLdapCache -s serverurl -c context -u user -p password See Using the stand-alone tool to clear the LDAP cache for details.
ibm.appcenter.ldap.referral Property that indicates whether referrals are supported by the JNDI API. If no value is given, the JNDI API will not handle LDAP referrals. Possible values are:
  • ignore: ignores referrals found in the LDAP server.
  • follow: automatically follows any referrals found in the LDAP server.
  • throw: causes an exception to occur for each referral found in the LDAP server.

See JNDI properties for Application Center for a complete list of LDAP properties that you can set.

Example of setting properties for ACL management with LDAP
This example shows the settings of the properties in the server.xml file required for ACL management with LDAP.

<jndiEntry jndiName="ibm.appcenter.ldap.active" value="true"/>
<jndiEntry jndiName="ibm.appcenter.ldap.connectionURL" value="ldap://employees.com:636"/>
<jndiEntry jndiName="ibm.appcenter.ldap.user.loginName" value="uid"/>
<jndiEntry jndiName="ibm.appcenter.ldap.user.base" value="dc=ibm,dc=com"/>
<jndiEntry jndiName="ibm.appcenter.ldap.group.base" value="dc=ibm,dc=com"/>
<jndiEntry jndiName="ibm.appcenter.ldap.user.displayName" value="sn"/>
<jndiEntry jndiName="ibm.appcenter.ldap.group.name" value="cn"/>
<jndiEntry jndiName="ibm.appcenter.ldap.group.uniquemember" value="uniqueMember"/>
<jndiEntry jndiName="ibm.appcenter.ldap.user.groupmembership" value="ibm-allGroups"/>
<jndiEntry jndiName="ibm.appcenter.ldap.cache.expiration.seconds" value="43200"/>
<jndiEntry jndiName="ibm.appcenter.ldap.security.sasl" value='"EXTERNAL"'/>
<jndiEntry jndiName="ibm.appcenter.ldap.referral" value='"follow"'/>
<jndiEntry jndiName="ibm.appcenter.ldap.user.filter" value='"(&amp;(uid=%v)(objectclass=inetOrgPerson))"'/>
<jndiEntry jndiName="ibm.appcenter.ldap.user.displayName.filter" value='"(&amp;(cn=%v)(objectclass=inetOrgPerson))"'/>
<jndiEntry jndiName="ibm.appcenter.ldap.group.filter" value='"(&amp;(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))"'/>

LDAP with Apache Tomcat

Configure the Apache Tomcat application server for LDAP authentication and configure security (Java™ Platform, Enterprise Edition) in the web.xml file of the Application Center.

To configure ACL management of the Application Center, configure LDAP for user authentication, map the Java™ EE roles of the Application Center to the LDAP roles, and configure the Application Center properties for LDAP authentication. Only the simple type of LDAP authentication is supported.

Configuration of LDAP authentication (Apache Tomcat)

Define the users who can access the Application Center console and the users who can log in with the mobile client by mapping Java™ Platform, Enterprise Edition roles to LDAP roles.

To configure ACL management of the Application Center, follow this process:

  • Configure LDAP for user authentication.
  • Map the Java Platform, Enterprise Edition (Java EE) roles of the Application Center to the LDAP roles.
  • Configure theApplication Center properties for LDAP authentication.

Restriction: Only the simple type of LDAP authentication is supported.

You configure the Apache Tomcat server for LDAP authentication and configure security (Java™ Platform, Enterprise Edition) in the web.xml file of theApplication Center Services web application (applicationcenter.war) and of the Application Center Console web application (appcenterconsole.war).

LDAP user authentication
You must configure a JNDIRealm in the server.xml file in the <Host> element. For more information about configuring a realm, see the Realm Component on the Apache Tomcat website.

Example of configuration on Apache Tomcat to authenticate against an LDAP server
This example shows how to configure user authentication on an Apache Tomcat server by comparing with the authorization of these users on a server enabled for LDAP authentication.

<Host appBase="webapps" autoDeploy="true" name="localhost" unpackWARs="true">
 ...
<Realm className="org.apache.catalina.realm.JNDIRealm"
       connectionURL="ldap://bluepages.ibm.com:389"
       userSubtree="true"
       userBase="ou=bluepages,o=ibm.com"
       userSearch="(emailAddress={0})"
       roleBase="ou=ibmgroups,o=ibm.com"
       roleName="cn"
       roleSubtree="true"
       roleSearch="(uniqueMember={0})"
       allRolesMode="authOnly"
       commonRole="appcenter"/>
 ...
</Host>

The value of connectionURL is the LDAP URL of your LDAP server.

The userSubtree, userBase, and userSearch attributes define how to use the name that is given to the Application Center in login form (in the browser message box) to match an LDAP user entry.

In the example, the definition of userSearch specifies that the user name is used to match the email address of an LDAP user entry.

The basis or scope of the search is defined by the value of the userBase attribute. In LDAP, an information tree is defined; the user base indicates a node in that tree.

Set the value of userSubtree to true; if it is set to false, the search runs only on the direct child nodes of the user base. It is important that the search penetrates the subtree and does not stop at the first level.

For authentication, you define only the userSubtree, userBase, and userSearch attributes. The Application Center also uses Java EE security roles. Therefore, you must map LDAP attributes to some Java EE roles. These attributes are used for mapping LDAP attributes to security roles:

  • roleBase
  • roleName
  • roleSubtree
  • roleSearch

In this example, the value of the roleSearch attribute matches all LDAP entries with a uniqueMember attribute whose value is the Distinguished Name (DN) of the authenticated user.

  • The roleBase attribute specifies a node in the LDAP tree below which the roles are defined.
  • The roleSubtree attribute indicates whether the LDAP search should search the entire subtree, whose root is defined by the value of roleBase, or only the direct child nodes.
  • The roleName attribute defines the name of the LDAP attribute.
  • The allRolesMode attribute specifies that you can use the asterisk (*) character as the value of role-name in the web.xml file. This attribute is optional.
  • The commonRole attribute adds a role that is shared by all authenticated users. This attribute is optional.

Mapping the Java EE roles of the Application Center to LDAP roles
After you define the LDAP request for the Java EE roles, you must change the web.xml file of the Application Center Services web application (applicationcenter.war) and of the Application Center Console web application (appcenterconsole.war) to map the Java EE roles of appcenteradmin and appcenteruser to the LDAP roles.

These examples, where LDAP users have LDAP roles, called MyLdapAdmin and MyLdapUser, show where and how to change the web.xml file. Replace the names MyLdapAdmin and MyLdapUser with the roles that are defined in your LDAP. Modify the following files:

  • tomcat_install_dir/webapps/appcenterconsole/WEB-INF/web.xml
  • tomcat_install_dir/webapps/applicationcenter/WEB-INF/web.xml

The security-role-ref element in the JAX_RS servlet

<servlet>
    <servlet-name>...</servlet-name>
    <servlet-class>...</servlet-class>
        <init-param>
            ...		
        </init-param>
       <load-on-startup>1</load-on-startup>
       <security-role-ref>
           <role-name>appcenteradmin</role-name>
           <role-link>MyLdapAdmin</role-link>
       </security-role-ref>
       <security-role-ref>
           <role-name>appcenteruser</role-name>
           <role-link>MyLdapUser</role-link>
       </security-role-ref>
</servlet>

The security-role element

<security-role>
    <role-name>MyLdapAdmin</role-name>
</security-role>
<security-role>
    <role-name>MyLdapUser</role-name>
</security-role>

The auth-constraint element
After you edit the security-role-ref and the security-role elements, you can use the roles that are defined in the auth-constraint elements to protect the web resources. Edit these roles for the appcenteradminConstraint element in both the web.xml file of both appcenterconsole and applicationcenter, and for the appcenteruserConstraint element in the appcenterconsole web.xml file.

<security-constraint>
        <display-name>appcenteradminConstraint</display-name>
        <web-resource-collection>
            ...
        </web-resource-collection>
        <auth-constraint>
            <role-name>MyLdapAdmin</role-name>
        </auth-constraint>
        <user-data-constraint>
            ...
        </user-data-constraint>
</security-constraint>

and

<security-constraint>
        <display-name>appcenteruserConstraint</display-name>
        <web-resource-collection>
            ...
        </web-resource-collection>
        <auth-constraint>
            <role-name>MyLdapUser</role-name>
        </auth-constraint>
        <user-data-constraint>
            ...
        </user-data-constraint>
</security-constraint>

Configuring LDAP ACL management (Apache Tomcat)

Use LDAP to define the users and groups who can install mobile applications with the Application Center by defining the Application Center LDAP properties through JNDI.

To configure LDAP ACL management of the Application Center; add an entry for each property in the <context> section of the Persistent Application Center Services application in the server.xml file. This entry should have the following syntax:

<Environment name="JNDI_property_name" value="property_value" type="java.lang.String" override="false"/>

Where:

  • JNDI_property_name is the name of the property you are adding.
  • property_value is the value of the property you are adding.
Property Description
ibm.appcenter.ldap.active Set to true to enable LDAP; set to false to disable LDAP.
ibm.appcenter.ldap.federated.active Since WebSphere Application Server Liberty profile V8.5.5: set to true to enable use of the federated registry; set to false to disable use of the federated registry, which is the default setting.
ibm.appcenter.ldap.connectionURL LDAP connection URL.
ibm.appcenter.ldap.user.base Search base of users.
ibm.appcenter.ldap.user.loginName LDAP login attribute.
ibm.appcenter.ldap.user.displayName LDAP attribute for the user name to be displayed, for example, a person’s full name.
ibm.appcenter.ldap.group.base Search base of groups.
ibm.appcenter.ldap.group.name LDAP attribute for the group name.
ibm.appcenter.ldap.group.uniquemember LDAP attribute that identifies the members of a group.
ibm.appcenter.ldap.user.groupmembership LDAP attribute that identifies the groups to which a user belongs.
ibm.appcenter.ldap.group.nesting Management of nested groups: if nested groups are not managed, set the value to false.
ibm.appcenter.ldap.user.filter LDAP user search filter for the attribute of user login name. Use %v as the placeholder for the login name attribute. This property is only required when LDAP users and groups are defined in the same subtree; that is, when the properties ibm.appcenter.ldap.user.base and ibm.appcenter.ldap.group.base have the same value.
ibm.appcenter.ldap.displayName.filter LDAP user search filter for the attribute of user display name. Use %v as the placeholder for the display name attribute. This property is only required when LDAP users and groups are defined in the same subtree; that is, when the properties ibm.appcenter.ldap.user.base and ibm.appcenter.ldap.group.base have the same value.
ibm.appcenter.ldap.group.filter LDAP group search filter. Use %v as the placeholder for the group attribute. This property is only required when LDAP users and groups are defined in the same subtree; that is, when the properties ibm.appcenter.ldap.user.base and ibm.appcenter.ldap.group.base have the same value.
ibm.appcenter.ldap.security.sasl The value of the security authentication mechanism when the LDAP external SASL authentication mechanism is required to bind to the LDAP server. The value depends on the LDAP server; usually, it is set to “EXTERNAL”.
ibm.appcenter.ldap.security.binddn Property that identifies the distinguished name of the user permitted to search the LDAP directory. Use this property only if security binding is required.
ibm.appcenter.ldap.security.bindpwd Property that identifies the password of the user who is allowed to search the LDAP directory. Use this property only if security binding is required. The password can be encoded with the “Liberty profile securityUtility” tool. Run the tool and then set the value of this property to the encoded password generated by the tool. The supported encoding types are xor and aes. Edit the Liberty profile server.xml file to check whether the classloader is enabled to load the JAR file that decodes the password.
ibm.appcenter.ldap.cache.expiration.seconds elay in seconds before the LDAP cache expires. If no value is entered, the default value is 86400, which is equal to 24 hours. Changes to users and groups on the LDAP server become visible to the Application Center after a delay, which is specified by ibm.appcenter.ldap.cache.expiration.seconds. The Application Center maintains a cache of LDAP data and the changes only become visible after the cache expires. By default, the delay is 24 hours. If you do not want to wait for this delay to expire after changes to users or groups, you can call this command to clear the cache of LDAP data: acdeploytool.sh -clearLdapCache -s serverurl -c context -u user -p password See Using the stand-alone tool to clear the LDAP cache for details.
ibm.appcenter.ldap.referral Property that indicates whether referrals are supported by the JNDI API. If no value is given, the JNDI API will not handle LDAP referrals. Possible values are:
  • ignore: ignores referrals found in the LDAP server.
  • follow: automatically follows any referrals found in the LDAP server.
  • throw: causes an exception to occur for each referral found in the LDAP server.

See JNDI properties for Application Center for a complete list of LDAP properties that you can set.

The example shows properties defined in the server.xml file.

<Environment name="ibm.appcenter.ldap.active" value="true" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.connectionURL" value="ldaps://employees.com:636" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.user.base" value="dc=ibm,dc=com" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.user.loginName" value="uid" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.user.displayName" value="cn" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.user.groupmembership" value="ibm-allGroups" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.group.base" value="dc=ibm,dc=com" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.group.name" value="cn" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.group.uniquemember" value="uniquemember" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.cache.expiration.seconds" value="43200" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.security.sasl" value="EXTERNAL" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.security.referral" value="follow" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.user.filter" value="(&amp;(uid=%v)(objectclass=inetOrgPerson))" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.user.displayName.filter" value="(&amp;(cn=%v)(objectclass=inetOrgPerson))" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.ldap.group.filter" value="(&amp;(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))" type="java.lang.String" override="false"/>

Managing the DB2 transaction log size

When you upload an application that is at least 40 MB with Persistent Mobile Foundation Application Center console, you might receive a transaction log full error.

The following system output is an example of the transaction log full error code.

DB2 SQL Error: SQLCODE=-964, SQLSTATE=57011

The content of each application is stored in the Application Center database.

The active log files are defined in number by the LOGPRIMARY and LOGSECOND database configuration parameters, and in size by the LOGFILSIZ database configuration parameter. A single transaction cannot use more log space than LOGFILSZ * (LOGPRIMARY + LOGSECOND) * 4096 KB.

The DB2 GET DATABASE CONFIGURATION command includes information about the log file size, and the number of primary and secondary log files.

Depending on the largest size of the Persistent Mobile Foundation application that is deployed, you might need to increase the DB2 log space.

Using the DB2 update db cfg command, increase the LOGSECOND parameter. Space is not allocated when the database is activated. Instead, the space is allocated only as needed.

Defining the endpoint of the application resources

When you add a mobile application from the Application Center console, the server-side component creates Uniform Resource Identifiers (URI) for the application resources (package and icons). The mobile client uses these URI to manage the applications on your device.

To manage the applications on your device, the Application Center console must be able to locate the Application Center REST services and to generate the required number of URI that enable the mobile client to find the Application Center REST services.

By default, the URI protocol, host name, and port are the same as those defined in the web application server used to access the Application Center console; the context root of the Application Center REST services is applicationcenter. When the context root of the Application Center REST services is changed or when the internal URI of the web application server is different from the external URI that can be used by the mobile client, the externally accessible endpoint (protocol, host name, and port) of the application resources must be defined by configuring the web application server. (Reasons for separating internal and external URI could be, for example, a firewall or a secured reverse proxy that uses HTTP redirection.)

The following figure shows a configuration with a secured reverse proxy that hides the internal address (192.168…). The mobile client must use the external address (appcntr.net).

Configuration with secured reverse proxy

Endpoint properties

Property name Purpose Example
ibm.appcenter.services.endpoint This property enables the Application Center console to locate the Application Center REST services. The value of this property must be specified as the external address and context root of the applicationcenter.war web application. You can use the asterisk (*) character as wildcard to specify that the Application Center REST services use the same value as the Application Center console. For example: ://:*/appcenter means use the same protocol, host, and port as the Application Center console, but use appcenter as context root. This property must be specified for the Application Center console application. https://appcntr.net:443/applicationcenter
ibm.appcenter.proxy.protocol This property specifies the protocol required for external applications to connect to the Application Center. https
ibm.appcenter.proxy.host This property specifies the host name required for external applications to connect to the Application Center. appcntr.net
ibm.appcenter.proxy.port This property specifies the port required for external applications to connect to the Application Center. 443

Jump to

Configuring the endpoint of the application resources (Liberty profile)

For the Liberty profile, configure the endpoint of the application resources through the JNDI environment.

Follow this procedure when you must change the URI protocol, host name, and port used by the Application Center client to manage the applications on your device.

Edit the server.xml file. To be able to define JNDI entries, the <feature> element must be defined correctly in the server.xml file:

<feature>jndi-1.0</feature>

Add an entry for each property in the <server> section of the server.xml file. This entry should have the following syntax:

<jndiEntry jndiName="JNDI_property_name" value="property_value"/>

Where:

  • JNDI_property_name is the name of the property that you are adding.
  • property_value is the value of the property that you are adding.
Property Description
ibm.appcenter.services.endpoint The URI of the Application Center REST services. In a scenario with a firewall or a secured reverse proxy, this URI must be the external URI and not the internal URI inside the local LAN.
ibm.appcenter.proxy.protocol The protocol of the application resources URI. This property is optional. It is only needed if the protocol of the external and of the internal URI are different.  
ibm.appcenter.proxy.host The host name of the application resources URI.
ibm.appcenter.proxy.port The port of the application resources URI. This property is optional. It is only needed if the protocol of the external and of the internal URI are different.

For a complete list of LAPD properties that you can set, see JNDI properties for Application Center.

Example of setting properties for configuring the endpoint

This example shows the settings of the properties in the server.xml file required for configuring the endpoint of the application resources.

<jndiEntry jndiName="ibm.appcenter.services.endpoint" value=" https://appcntr.net:443/applicationcenter" />
<jndiEntry jndiName="ibm.appcenter.proxy.protocol" value="https" />
<jndiEntry jndiName="ibm.appcenter.proxy.host" value="appcntr.net" />
<jndiEntry jndiName="ibm.appcenter.proxy.port"  value=" 443"/>

You can use the asterisk (*) character as wildcard to specify that the Application Center REST services use the same value as the Application Center console. For example: *://*:*/appcenter means use the same protocol, host, and port as the Application Center console, but use appcenter as context root.

Configuring the endpoint of the application resources (Apache Tomcat)

For the Apache Tomcat server, configure the endpoint of the application resources in the server.xml file.

Follow this procedure when you must change the URI protocol, host name, and port used by the Application Center client to manage the applications on your device.

Edit the server.xml file in the conf directory of your Apache Tomcat installation.
Add an entry for each property in the <context> section of the corresponding application. This entry should have the following syntax:

<Environment name="JNDI_property_name" value="property_value" type="property_type" override="false"/>

Where:

  • JNDI_property_name is the name of the property you are adding.
  • property_value is the value of the property you are adding.
  • property_type is the type of the property you are adding.
Property Type Description
ibm.appcenter.services.endpoint java.lang.String The URI of the Application Center REST services (applicationcenter.war). In a scenario with a firewall or a secured reverse proxy, this URI must be the external URI and not the internal URI inside the local LAN.
ibm.appcenter.proxy.protocol java.lang.String The protocol of the application resources URI. This property is optional. It is only needed if the protocol of the external and of the internal URI are different.
ibm.appcenter.proxy.host java.lang.String The host name of the application resources URI.
ibm.appcenter.proxy.port java.lang.Integer The port of the application resources URI. This property is optional. It is only needed if the protocol of the external and of the internal URI are different.

For a complete list of JNDI properties that you can set, see JNDI properties for PMF Application Center.

Example of setting server.xml properties for configuring the endpoint

This example shows the settings of the properties in the server.xml file required for configuring the endpoint of the application resources.

In the <context> section of the Application Center console application:

<Environment name="ibm.appcenter.services.endpoint" value="https://appcntr.net:443/applicationcenter" type="java.lang.String" override="false"/>

You can use the asterisk (*) character as wildcard to specify that the Application Center REST services use the same value as the Application Center console. For example: *://*:*/appcenter means use the same protocol, host, and port as the Application Center console, but use appcenter as context root.

In the <context> section of the Application Center services application:

<Environment name="ibm.appcenter.services.endpoint" value="https://appcntr.net:443/applicationcenter" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.proxy.protocol" value="https" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.proxy.host" value="appcntr.net" type="java.lang.String" override="false"/>
<Environment name="ibm.appcenter.proxy.port"  value="443" type="java.lang.Integer" override="false"/>

Configuring Secure Sockets Layer (SSL)

Learn about configuring SSL for the Application Center on supported application servers and the limitations of certificate verification on mobile operating systems.

You can configure the Application Center with SSL or without SSL, unless you intend to install applications on iOS devices. For iOS applications, you must configure the Application Center server with SSL.

SSL transmits data over the network in a secured channel. You must purchase an official SSL certificate from an SSL certificate authority. The SSL certificate must be compatible with Android and iOS. Self-signed certificates do not work with the Application Center.

When the client accesses the server through SSL, the client verifies the server through the SSL certificate. If the server address matches the address that is filed in the SSL certificate, the client accepts the connection. For the verification to be successful, the client must know the root certificate of the certificate authority. Many root certificates are preinstalled on Android and iOS devices. The exact list of pre-installed root certificates varies between versions of mobile operating systems.

For information about the certificates supported on mobile operating system versions, consult the SSL certificate authority.

If the SSL certificate verification fails, a normal web browser requests confirmation to contact an untrusted site. The same behavior occurs when you use a self-signed certificate that was not purchased from a certificate authority. When mobile applications are installed, this control is not performed by a normal web browser, but by operating system calls.

Some versions of Android and iOS do not support this confirmation dialog in system calls. This limitation is a reason to avoid self-signed certificates or SSL certificates that are not suited to mobile operating systems. On Android and iOS you can install a self-signed CA certificate on the device to enable the device to handle system calls regarding this self-signed certificate. This practice is not appropriate for Application Center in a production environment, but it can be suitable during the testing period. For details, see Managing and installing self-signed CA certificates in an Application Center test environment below.

Jump to

Configuring SSL for Liberty profile

Create a keystore, import the Secure Socket Layer (SSL) certificate, and edit the server.xml file to configure SSL on Liberty profile.
Follow the steps in this procedure to configure SSL on Liberty profile.

  1. Create a keystore for your web server; use the securityUtility with the createSSLCertificate option.
  2. Import the SSL certificate and the corresponding chain certificate into your keystore by following the instructions provided by the certificate authority.

  3. Enable the ssl-1.0 Liberty feature in the server.xml file.

    <featureManager>
   <feature>ssl-1.0</feature>
</featureManager>

  4. Add the keystore service object entry to the server.xml file. The keyStore element is called defaultKeyStore and contains the keystore password. For example:

    <keyStore id="defaultKeyStore" location="/path/to/myKeyStore.p12"
       password="myPassword" type="PKCS12"/>

  5. Make sure that the value of the httpEndpoint element in the server.xml file defines the httpsPort attribute. For example:

    <httpEndpoint id="defaultHttpEndpoint” host="*" httpPort="9080” httpsPort="9443" >
  6. Restart the web server. Now you can access the web server by https://myserver:9443/...
Configuring SSL for Apache Tomcat

Create a keystore, import the Secure Socket Layer (SSL) certificate, and edit the conf/server.xml file to define a connector for SSL on Apache Tomcat. Follow the steps in this procedure to configure SSL on Apache Tomcat. See SSL Configuration HOW-TO for more details and examples of configuring SSL for Apache Tomcat.

  1. Create a keystore for your web server. You can use the Java™ keytool command to create a keystore.

    keytool -genkey -alias tomcat -keyalg RSA -keystore /path/to/keystore.jks
  2. Import the SSL certificate and the corresponding chain certificate into your keystore by following the instructions provided by the certificate authority.

  3. Edit the conf/server.xml file to define a connector to use SSL. This connector must point to your keystore.

    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
            maxThreads="150" scheme="https" secure="true"
            clientAuth="false" sslProtocol="TLS"
            keystoreFile="/path/to/keystore.jks"
            keystorePass="mypassword" />
  4. Restart the web server. Now you can access the web server by https://myserver:8443/...
Managing and installing self-signed CA certificates in an PMF Application Center test environment

Use self-signed certificate authority (CA) certificates in test environments to install applications with Application Center on a mobile device from a secured server.

Uploading or deleting a certificate
When you install the Application Center mobile client from OTA (the bootstrap page), the device user must upload and install the self-signed CA file before the Application Center mobile client is installed.

When you use Application Center for a test installation, the administrator might not have a real Secure Sockets Layer (SSL) certificate available. You might want to use a self-signed CA certificate. Such certificates work if they get installed on the device as root certificate. As an administrator, you can easily distribute self-signed CA certificates to devices.

The following procedure focuses mostly on the iOS and Android environments. Support for X.509 certificates comes from the individual mobile platforms, not from Persistent Mobile Foundation. For more information about specific requirements for X.509 certificates, see the documentation of each mobile platform.

Managing self-signed certificates: in your role of administrator of Application Center, you can access the list of registered self-signed CA certificates to upload or delete certificates.

  1. To display Application Center settings, click the gear icon Icon to access Application Center settings.
  2. To display the list of registered certificates, select Self Signed Certificates.
  3. Upload or delete a certificate.
    • To upload a self-signed CA certificate, in the Application Center console, click Upload a certificate and select a certificate file.

    Note: The certificate file must be in PEM file format. Typical file name suffixes for this type of file are .pem, .key, .cer, .cert. The certificate must be a self-signed one, that is, the values of the Issuer and Subject fields must be the same. And the certificate must be a CA certificate, that is, it must have the X509 extension named BasicConstraint set to CA:TRUE.

  • To delete a certificate, click the trash can icon on the right of the certificate file name in the list.

Installing a self-signed CA certificate on a device
Registered self-signed CA certificates are available through the bootstrap page at http://hostname:portnumber/appcenterconsole/installers.html.

Where:

  • hostname is the name of the server that hosts the Application Center console.
  • portnumber is the corresponding port number.
  1. Click the SSL Certificates tab.
  2. To display the details of a certificate, select the appropriate registered certificate.
  3. To download and install the certificate on the device, click Install.

JNDI properties for Application Center

You can configure some JNDI properties for Application Center.

Property Description
appcenter.database.type The database type, which is required only when the database is not specified in appcenter.jndi.name.
appcenter.jndi.name The JNDI name of the database. This parameter is the normal mechanism to specify the database. The default value is java:comp/env/jdbc/AppCenterDS.
appcenter.openjpa.ConnectionDriverName The fully qualified class name of the database connection driver class. This property is needed only when the database is not specified in appcenter.jndi.name.
appcenter.openjpa.ConnectionPassword The password for the database connection. Set this property only when the database is not specified in appcenter.jndi.name.
appcenter.openjpa.ConnectionURL The URL for the database connection driver class. Set this property only when the database is not specified in appcenter.jndi.name.
appcenter.openjpa.ConnectionUserName The user name for the database connection. Set this property only when the database is not specified in appcenter.jndi.name.
ibm.appcenter.apns.p12.certificate.isDevelopmentCertificate Set this property to true to specify whether the certificate that enables Application Center to send push notifications about updates of iOS applications is a development certificate. Set the property to false if it is not a development certificate. See Configuring the Application Center server for connection to Apple Push Notification Services.
ibm.appcenter.apns.p12.certificate.location The path to the file of the development certificate that enables Application Center to send push notifications about updates of iOS applications. For example, /Users/someUser/someDirectory/apache-tomcat/conf/AppCenter_apns_dev_cert.p12. See Configuring the Application Center server for connection to Apple Push Notification Services.
ibm.appcenter.apns.p12.certificate.password The password of the certificate that enables Application Center to send push notifications about updates of iOS applications. See Configuring the Application Center server for connection to Apple Push Notification Services.
ibm.appcenter.forceUpgradeDBTo60 The database is automatically updated when the Application Center web application starts. If you want to repeat this update, you can set this parameter to true and start the web application again. Later you can reset this parameter to false.
ibm.appcenter.gcm.signature.googleapikey The Google API key that enables Application Center to send push notifications about updates for Android applications. For example, AIxaScCHg0VSGdgfOZKtzDJ44-oi0muUasMZvAs. See Configuring the Application Center server for connection to Google Cloud Messaging.
ibm.appcenter.ios.plist.onetimeur Specifies whether URLs stored in iOS plist manifests use the one-time URL mechanism without credentials. If you set this property to true, the security level is medium, because one-time URLs are generated with a cryptographic mechanism so that nobody can guess the URL but do not require the user to log in. Setting this property to false provides maximal security, because the user is then required to log in for each URL. However, requesting the user to log in multiple times when you install an iOS application can degrade the user experience. See Installing the client on an iOS mobile device.
ibm.appcenter.ldap.active Specifies whether Application Center is configured for LDAP. Set this property to true to enable LDAP or to false to disable LDAP. See Managing users with LDAP.
ibm.appcenter.ldap.cache.expiration.seconds The Application Center maintains a cache of LDAP data and the changes become visible only after the cache expires. Specify the number of seconds during which an entry in the LDAP cache is valid. Set this property to a value greater than 3600 (1 hour) to reduce the amount of LDAP requests. If no value is entered, the default value is 86400, which is equal to 24 hours. If you need to clear the cache of LDAP data manually, enter this command: acdeploytool.sh -clearLdapCache -s serverurl -c context -u user -p password. See Using the stand-alone tool to clear the LDAP cache.
ibm.appcenter.ldap.connectionURL The URL to access the LDAP server when no Virtual Member Manager (VMM) is used. See Configuring LDAP ACL management (Liberty profile) and Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.federated.active Specifies whether Application Center is configured for LDAP with federated repositories. Since WebSphere Application Server Liberty profile V8.5.5., set this property to true to enable use of the federated registry. Set this property to false to disable use of the federated registry, which is the default setting. See Managing users with LDAP.
ibm.appcenter.ldap.group.base The search base to find groups when you use LDAP without Virtual Member Manager (VMM). See Configuring LDAP ACL management (Liberty profile) and Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.group.filter LDAP group search filter. Use %v as the placeholder for the group attribute. This property is only required when LDAP users and groups are defined in the same subtree; that is, when the properties ibm.appcenter.ldap.user.base and ibm.appcenter.ldap.group.base have the same value.
ibm.appcenter.ldap.group.name The group name attribute when you use LDAP without Virtual Member Manager (VMM). See Configuring LDAP ACL management (Liberty profile) and Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.group.nesting Specifies whether the LDAP contains nested groups (that is, groups in groups) when you use LDAP without Virtual Member Manager (VMM). Setting this property to false speeds up LDAP access because the groups are not searched recursively. See Configuring LDAP ACL management (Liberty profile) and Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.group.uniquemember Specifies the members of a group when you use LDAP without Virtual Member Manager (VMM). This property is the inverse of ibm.appcenter.ldap.user.groupmembership. See Configuring LDAP ACL management (Liberty profile) and Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.referral Specifies whether referrals are supported by the JNDI API. If no value is specified, the JNDI API does not handle LDAP referrals. Here are the possible values:
  • ignore: Ignores referrals that are found in the LDAP server.
  • follow: Automatically follows any referrals that are found in the LDAP server.
  • throw: Causes an exception to occur for each referral found in the LDAP server.
ibm.appcenter.ldap.security.binddn The distinguished name of the user that is allowed to search the LDAP directory. Use this property only if security binding is required.
ibm.appcenter.ldap.security.bindpwd The password of the user that is permitted to search the LDAP directory. Use this property only if security binding is required.

The password can be encoded with the Liberty profile securityUtility tool. Run the tool and then set the value of this property to the encoded password that is generated by the tool.

Edit the Liberty profile server.xml file to check whether the classloader is enabled to load the JAR file that decodes the password.

See Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.security.sasl Specifies the security authentication mechanism when the LDAP external SASL authentication mechanism is required to bind to the LDAP server. The value depends on the LDAP server and it is typically set to EXTERNAL. When this property is set, security authentication is required to connect to LDAP without Virtual Member Manager (VMM). See Configuring LDAP ACL management (Liberty profile) and Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.user.base The search base to find users when you use LDAP without Virtual Member Manager (VMM). See Configuring LDAP ACL management (Liberty profile) and Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.user.displayName The display name attribute, such as the user’s real name, when you use LDAP without Virtual Member Manager (VMM). See Configuring LDAP ACL management (Liberty profile) and Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.displayName.filter LDAP user search filter for the attribute of ibm.appcenter.ldap.user.displayName. Use %v as the placeholder for the display name attribute.

This property is required only when LDAP users and groups are defined in the same subtree; that is, when the properties ibm.appcenter.ldap.user.base and ibm.appcenter.ldap.group.base have the same value.
ibm.appcenter.ldap.user.filter LDAP user search filter for the attribute of ibm.appcenter.ldap.user.loginName. Use %v as the placeholder for the login name attribute.

This property is required only when LDAP users and groups are defined in the same subtree; that is, when the properties ibm.appcenter.ldap.user.base and ibm.appcenter.ldap.group.base have the same value.
ibm.appcenter.ldap.user.groupmembership Specifies the groups of a member when you use LDAP without Virtual Member Manager (VMM). This property is the inverse of ibm.appcenter.ldap.group.uniquemember. This property is optional, but if it is specified, LDAP access is faster. See Configuring LDAP ACL management (Liberty profile) and Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.user.loginName The login name attribute when you use LDAP without Virtual Member Manager (VMM). See Configuring LDAP ACL management (Liberty profile) and Configuring LDAP ACL management (Apache Tomcat).
ibm.appcenter.ldap.vmm.active Set this property to true to specify that LDAP is done through Virtual Member Manager (VMM), or to false otherwise. See Configuring LDAP ACL management for WebSphere Application Server V8.x.
ibm.appcenter.ldap.vmm.adminpwd The password when LDAP is done through Virtual Member Manager (VMM). See Configuring LDAP ACL management for WebSphere Application Server V8.x.
ibm.appcenter.ldap.vmm.adminuser The user when LDAP is done through Virtual Member Manager (VMM). See Configuring LDAP ACL management for WebSphere Application Server V8.x.
ibm.appcenter.logging.formatjson This property has an effect only when ibm.appcenter.logging.tosystemerror is set to true. If this property is enabled, it formats JSON responses in logging messages that are directed to System.Error. Setting this property is helpful when you debug the server.
ibm.appcenter.logging.tosystemerror Specifies whether all logging messages are also directed to System.Error. Setting this property is helpful when you debug the server.
ibm.appcenter.openjpa.Log This property is passed to OpenJPA and enables JPA logging. For details, see the Apache OpenJPA User’s Guide.
ibm.appcenter.proxy.host If the Application Center server is behind a firewall or reverse proxy, this property specifies the address of the host. Setting this property allows a user outside the firewall to reach the Application Center server. Typically, this property is the address of the proxy. See Defining the endpoint of the application resources.
ibm.appcenter.proxy.port If the Application Center server is behind a firewall or reverse proxy, this property specifies the address of the host. Setting this property allows a user outside the firewall to reach the Application Center server. Typically, this property is the port of the proxy, for example 443. It is needed only if the protocol of the external URI and the protocol of the internal URI are different. See Defining the endpoint of the application resources.
ibm.appcenter.proxy.protocol If the Application Center server is behind a firewall or reverse proxy, this property specifies the protocol (http or https). Setting this property allows a user outside the firewall to reach the Application Center server. Typically, this property is set to the protocol of the proxy. For example, appcntr.net. This property is needed only if the protocol of the external and of the internal URI are different. See Defining the endpoint of the application resources.
ibm.appcenter.proxy.scheme This property is just an alternative name for ibm.appcenter.proxy.protocol.
ibm.appcenter.push.schedule.period.amount Specifies the time schedule when you send push notifications of application updates. When applications are frequently changed on the server, set this property to send batches of notifications. For example, send all notifications that happened within the past hour, instead of sending each individual notification.
ibm.appcenter.push.schedule.period.unit Specifies the unit for the time schedule when you send push notifications of application updates.
ibm.appcenter.services.endpoint Enables the Application Center console to locate the Application Center REST services. Specify the external address and context root of the applicationcenter.war web application. In a scenario with a firewall or a secured reverse proxy, this URI must be the external URI and not the internal URI inside the local LAN. For example, https://appcntr.net:443/applicationcenter. See Defining the endpoint of the application resources.
ibm.appcenter.services.iconCacheMaxAge Specifies the number of seconds during which cached icons remain valid for the Application Center console and the client. Application icons rarely change, therefore they are cached. Specify values larger than 600 (10 min) to reduce the amount of data transfer for the icons.
mfp.jndi.configuration Optional. If the JNDI configuration is injected into the WAR files or provided as a shared library, the value of this property is the name of the JNDI configuration. You can also specify this value as a system property.
mfp.jndi.file Optional. If the JNDI configuration is stored as an external file, the value of this property is the path of a file that describes the JNDI configuration. You can also specify this value as a system property.

Configuring WebSphere Application Server to support applications in public app stores

Configure WebSphere Application Liberty profile before access to public app stores through application links, because of the use of SSL connections.

The constraint imposed by the use of SSL connections requires the root certificates of public app stores to exist in the WebSphere truststore before you can use application links to access these public stores. The configuration requirement applies to WebSphere Application Server Liberty profile.

The root certificate of Google play must be imported into the WebSphere truststore before you can use application links to Google play.
The root certificate of Apple iTunes must be imported into the WebSphere truststore before you can use application links to iTunes.

Jump to

Configuring Liberty profile when IBM JDK is used

Configure Liberty profile to use default JSSE socket factories instead of SSL socket factories of WebSphere Application Server when IBM JDK is used.

The purpose is to configure the IBM JDK SSL factories to be compatible with Liberty profile. This configuration is required only when IBM JDK is used. The configuration does not apply for use of Oracle JDK. By default, IBM JDK uses the SSL socket factories of WebSphere Application Server. These factories are not supported by Liberty profile.

Exception when WebSphere Application Server SSL socket factories are used

If you use the IBM JDK of WebSphere Application Server, this exception could occur because this JDK uses SSL socket factories that are not supported by the Liberty profile. In this case, follow the requirements documented in Troubleshooting tips.

java.net.SocketException: java.lang.ClassNotFoundException: Cannot find the specified class com.ibm.websphere.ssl.protocol.SSLSocketFactory
      at javax.net.ssl.DefaultSSLSocketFactory.a(SSLSocketFactory.java:11)
      at javax.net.ssl.DefaultSSLSocketFactory.createSocket(SSLSocketFactory.java:6)
      at com.ibm.net.ssl.www2.protocol.https.c.afterConnect(c.java:161)
      at com.ibm.net.ssl.www2.protocol.https.d.connect(d.java:36)
      at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1184)
      at java.net.HttpURLConnection.getResponseCode(HttpURLConnection.java:390)
      at com.ibm.net.ssl.www2.protocol.https.b.getResponseCode(b.java:75)
      at com.ibm.ws.jmx.connector.client.rest.internal.RESTMBeanServerConnection.loadJMXServerInfo(RESTMBeanServerConnection.java:142)
      at com.ibm.ws.jmx.connector.client.rest.internal.RESTMBeanServerConnection.<init>(RESTMBeanServerConnection.java:114)
      at com.ibm.ws.jmx.connector.client.rest.internal.Connector.connect(Connector.java:315)
      at com.ibm.ws.jmx.connector.client.rest.internal.Connector.connect(Connector.java:103)
▲
Last modified on