Before You Start
AppSpokes requires MongoDB as its database, version 3.2 and above.
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:
- Open and edit the connectionsProvider.xml file from the oauth20 directory, e.g. /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/connectionsCell01/oauth20.
Add a new entry <value>appspokes-uem</value>, so it will look something like below.
- Restart the Connections node.
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:
- Download and unzip the AppSpokes UEM archive file (appspokes-hub-x.x.x.zip) to the desired location, e.g. /opt/appspokes.
Grant execute permission of the launch script (appspokes-hub) in the bin directory.
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.
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.
|Secret used to encrypt and secure user session cookies.|
|Fully qualified URL to access the application, e.g.where domain is your organization's domain|
|Set to true if the application is running HTTPS (highly recommended), otherwise false.|
|Set to false for running on-prem.|
|Secret used to sign and secure and sign communication with other spoke applications.|
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.
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.
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.
|hibernate.ogm.datastore.provider||This will always be set to mongodb.|
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.database||The name of database you have created earlier.|
|hibernate.ogm.datastore.username||The username for the account to connect to the database with.|
|hibernate.ogm.datastore.password||The password for the account to connect to the database with.|
|hibernate.ogm.mongodb.driver.sslEnabled||Set to true if SSL is required to connect to the database, otherwise set to false.|
|hibernate.ogm.mongodb.driver.sslInvalidHostNameAllowed||Set to true if the SSL certificated used is a self-signed certificate.|
Set the authentication mechanism used by your MongoDB server, available options are:
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_uem_url/onboarding/start. You should see something similar to the screenshot below:
The Organization Name you enter here will be used later on to sign into AppSpokes UEM, so make sure you do not forget it.
- Enter your email address, fully qualified URL to your IBM Connections, and name of your organization.
- Click the Continue button.
For the second step, you will see something similar to the screenshot below:
- Enter the Client ID and Client Secret you have from the Create OAuth 2 client section earlier.
- 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:
- Log into AppSpokes UEM with a administrative user account.
- Click on the Manage Applications link.
- Click the Register an application button.
- Enter the fully qualified URL to the integration application (e.g. For Shared Secret, enter the value of jwt.secret used during the setup of the application.
- 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.
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:
|Full path to the Java keystore file which contains the SSL certificate.|
|Password to access the Java keystore. Default keystore password is changeit.|
|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 number. If you are running more than one application on the same server, make sure you assign a different port number here.|
- Before You Start
- Database Setup
- IBM Connections Setup
- Onboard your organization
- Register integration applications in UEM
- Running HTTPS