Skip to end of metadata
Go to start of metadata

Before You Start

Make sure you have reviewed both Supported Platforms and System Requirements pages.

Database Setup

AppSpokes requires MongoDB as its database, version 3.2 and above.

Creating database

Icon

If you are running MongoDB with SSL, you must import the certificate into Java's truststore, and set hibernate.ogm.mongodb.driver.sslEnabled to true (see Connecting to database section below).

Make sure you refer to the official MongoDB documentation on how to create database. Once you have created the database and account, AppSpokes UEM will automatically create the necessary collections and indexes for you.

IBM Connections Setup

The next step is to create an OAuth 2 client for UEM in IBM Connections. This will be used to as the authentication mechanism to log into AppSpokes UEM.

Create OAuth 2 client

To create a new OAuth 2 client, run the following commands:

That will create a new OAuth 2 client with a client id of appspokes-uem in Connections. We now need to find out the auto-generated client secret, by running the command below:

Note down both the client id and secret, as they will be needed later.

We now need to enable the new OAuth 2 client as a trusted client:

  1. Open and edit the connectionsProvider.xml file from the oauth20 directory, e.g. /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/connectionsCell01/oauth20.
  2. Add a new entry <value>appspokes-uem</value>, so it will look something like below.

  3. Restart the Connections node.

Deployment

Deploying AppSpokes UEM requires all the following packages to be installed:

  • AppSpokes UEM application

Deploying AppSpokes UEM

Instructions below assumes AppSpokes UEM is deployed to a Linux system. To deploy AppSpokes UEM, follow the steps below:

  1. Download and unzip the AppSpokes UEM archive file (appspokes-hub-x.x.x.zip) to the desired location, e.g. /opt/appspokes.
  2. Grant execute permission of the launch script (appspokes-hub) in the bin directory.

  3. Create a dedicated user to run AppSpokes UEM. It is important that you do not run the application using the root user.

Setting up administrator users

Since AppSpokes will be using IBM Connections's user repository (which will be backed by an LDAP) to manage access, all you need to do is to specify a list of users that will be granted administrative access. To do this, open the access.conf file from the conf directory, and add the user emails, seperated by a comma.

access.conf

Specifying application properties

There are a number of properties that need to be set before the application can start operating. These can be configured in the customize.conf file from the conf directory.

PropertyDescription

play.crypto.secret

Secret used to encrypt and secure user session cookies.

application.url

Fully qualified URL to access the application, e.g. https://uem.domain.com where domain is your organization's domain

application.secure

Set to true if the application is running HTTPS (highly recommended), otherwise false.

application.cloud

Set to false for running on-prem.

jwt.secret

Secret used to sign and secure and sign communication with other spoke applications.

enc.secret

Secret used to encrypt data stored in database. The length of the secret needs to be multiples of 8 characters, recommended to be 32 characters long to give you 256 bit encryption.

* If using OracleJDK, the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files need to be manually install in order to support strong encryption.

Connecting to database

To connect AppSpokes UEM to the database, there are two files you need to configure. First is the database.conf file in the conf directory.

ParameterDescription
core-pool-size-min

Minimum number of threads to be created for the database connections pool. This should be set to something small (e.g. 10) to reduce startup overhead. As demands grow, the pool size will be dynamically adjusted.

core-pool-size-max

Maximum number of threads to be created for the database connections pool. This should be no more than the amount of connections allocated in the database for the application.

The second file is the persistence.xml file in conf/META-INF directory.

ParameterDescription
hibernate.ogm.datastore.providerThis will always be set to mongodb.
hibernate.ogm.datastore.host

The server host and port of your MongoDB server, if you have a replica set, you can put them both in.

For example: server_host_1:19313,server_host_2:19313

hibernate.ogm.datastore.databaseThe name of database you have created earlier.
hibernate.ogm.datastore.usernameThe username for the account to connect to the database with.
hibernate.ogm.datastore.passwordThe password for the account to connect to the database with.
hibernate.ogm.mongodb.driver.sslEnabledSet to true if SSL is required to connect to the database, otherwise set to false.
hibernate.ogm.mongodb.driver.sslInvalidHostNameAllowedSet to true if the SSL certificated used is a self-signed certificate.
hibernate.ogm.mongodb.authentication_mechanism

Set the authentication mechanism used by your MongoDB server, available options are:

  • SCRAM_SHA_1: The SCRAM SHA 1 Challenge Response mechanism.
  • PLAIN: The PLAIN mechanism.

Using environmental variable

For administrator users and application properties can be set using environmental variables. This is especially useful if you do not want to hard code sensitive information such as encryption secrets on a file, or if you want to create scripts to automate processes. To specify configuration properties via environmental variables, simply add -D in-front the property, such as:

Starting up the application

With everything configured, you can start up the application by running the startup script file from the bin directory, appspokes-hub for Linux, and appspokes-hub.bat for Windows.

Onboard your organization

Once the application is up and running, open your browser and go to https://your_uem_url/onboarding/start. You should see something similar to the screenshot below:

Icon

The Organization Name you enter here will be used later on to sign into AppSpokes UEM, so make sure you do not forget it.

  1. Enter your email address, fully qualified URL to your IBM Connections, and name of your organization.
  2. Click the Continue button.

For the second step, you will see something similar to the screenshot below:

  1. Enter the Client ID and Client Secret you have from the Create OAuth 2 client section earlier.
  2. Click the Submit button to continue.

For the third step, click on the Login with IBM Connections button to log into the application with your IBM Connections account. If everything is set up correctly, you will be taken to IBM Connections and asked to log in. Once you have logged in, you will be redirected back and everything will be ready to go.

Congratulations! You have now completed deployment and installation of AppSpokes UEM. You can proceed to deploying an AppSpokes integration application such as Box, JIRA, SharePoint Online etc. 

Register integration applications in UEM

Note: this step will need to be performed for every integration application, but first you'll need to deploy the integration application. Return to this part of the documentation after completing the deployment but before installing the integration application in UEM.

Before you can install and make an integration available to use, you need to first register it with the AppSpokes UEM. To do this:

  1. Log into AppSpokes UEM with a administrative user account.
  2. Click on the Manage Applications link.
  3. Click the Register an application button.
  4. Enter the fully qualified URL to the integration application (e.g. https://sharepoint-online-spoke.domain.com) in Base URL field.  For Shared Secret, enter the value of jwt.secret used during the setup of the application.
  5. Click on the Register button to register the application.

Once successfully registered, the new integration application will be listed and available for you to install.

Running HTTPS

Icon

If you are using a self signed certificate, make sure you import it into the Java truststore, otherwise, you will run into SSL handshake errors.

 

There are two ways to run AppSpokes with HTTPS:

  • SSL terminate at a front web server such as Apache or Nginx
  • SSL terminate at the application itself

If you are running AppSpokes behind a web server such as Apache or Nginx, which is a recommended for production, you can set up SSL on the web server, and terminate SSL there. This way, AppSpokes application server can remain running on normal HTTP, and delegate SSL handling to the web server.

If you are not running AppSpokes behind a web server and wish for the application to handle SSL itself, then you need to tell the application which port to run HTTPS on, and where the keystore containing the certificate is. You can do this via environment variables:

ParameterDescription

play.server.https.keyStore.path

Full path to the Java keystore file which contains the SSL certificate.

play.server.https.keyStore.password

Password to access the Java keystore. Default keystore password is changeit.

https.port

HTTPS port number. If you are running more than one application on the same server, make sure you assign a different port number here.

http.port

HTTP port number. If you are running more than one application on the same server, make sure you assign a different port number here.
  • No labels