Setting up workspace for Janssen development

This is a step-by-step guide for developers and contributors to setup Janssen development environment on a personal workstation. Once setup, it will enable building and testing Janssen project components locally.

Here we are handcrafting the Janssen setup so we can understand each component and setting that is necessary to run Janssen server and tests. You can also leverage IDE based development environment setup.

For the purpose of this guide, we are following steps and commands required on Ubuntu OS (version 18 or above). For all other OS platforms, like Windows, Mac, same steps and commands with platform specific changes can easily be derived.

Pre-requisites

Download and Install required software

JDK

For development as well as at runtime, Janssen requires any JDK with version 8 or above. Janssen in production environment uses Amazon Corretto (11.0.8) which is an OpenJDK distribution. You can download it from here.

Git

Janssen code is hosted on Github. You can use any Git client to interact with repositories.

Maven

Maven is a build tool used by Janssen. You can download it from here

MySQL

Janssen uses persistance storage to hold configuration and transactional data. Janssen supports variety of persistance technologies including LDAP, RDBMS and cloud storage. For this guide, we are going to use MySQL relational database as our persistance store. You can download and install MySQL from here

Jetty server

Janssen uses Jetty as web application server. You can download and install Jetty 9 from here.

Setup environment variables

Get code

Setup data store

Janssen uses persistance storage to hold configuration and transactional data. Janssen supports variety of persistance mechanisms including LDAP, RDBMS and cloud storage. For this guide, we are going to use MySQL relational database as a persistance store.

As a first step, let’s create schema and users.

Next, we will load basic configuration data into MySQL. This data is required by Janssen modules at the time of start up. We will use a helper script that will create required schema, tables, users, permissions and also insert basic configuration data in required tables.

Setup Configuration Files

Janssen stores configuration required at the boot time in the file system. It is stored at /etc/jans/conf. We need to create this directory on our local file system.

sudo mkdir /etc/jans

sudo mkdir /etc/jans/conf

mkdir $JETTY_BASE/custom

mkdir $JETTY_BASE/custom/pages

Now, we need to copy teplates of these configuration files from our code base.

sudo cp <auth-server-code-dir>/server/target/conf/* /etc/jans/conf/

Among copied files, there are two files that are notable:

Edit values in both these files as recommended below.

sudo vim /etc/jans/conf/jans.properties

sudo vim /etc/jans/conf/jans-sql.properties

Properties of jans-sql.properies listed above are most likely to be customised as per your local setup. Other properties from this file can be set to standard values as given below.

connection.driver-property.serverTimezone=UTC
# Prefix connection.driver-property.key=value will be coverterd to key=value JDBC driver properties
#connection.driver-property.driverProperty=driverPropertyValue

#connection.driver-property.useServerPrepStmts=false
connection.driver-property.cachePrepStmts=false
connection.driver-property.cacheResultSetMetadata=true
connection.driver-property.metadataCacheSize=500
#connection.driver-property.prepStmtCacheSize=500
#connection.driver-property.prepStmtCacheSqlLimit=1024

# Password hash method
password.encryption.method=SSHA-256

# Connection pool size
connection.pool.max-total=40
connection.pool.max-idle=15
connection.pool.min-idle=5

# Max time needed to create connection pool in milliseconds
connection.pool.create-max-wait-time-millis=20000

# Max wait 20 seconds
connection.pool.max-wait-time-millis=20000

# Allow to evict connection in pool after 30 minutes
connection.pool.min-evictable-idle-time-millis=1800000

binaryAttributes=objectGUID
certificateAttributes=userCertificate

Setup SSL

Janssen uses secure socket layer (SSL) to secure HTTP communication. To enable same of our local setup, we need to configure self signed ceritificates.


keytool -genkeypair -alias jetty -keyalg EC -groupname secp256r1 -keypass secret -validity 3700 -storetype JKS -keystore /tmp/keystore.test.local.jans.io.jks -storepass secret

What is your first and last name?
  [Unknown]:  test.local.jans.io
What is the name of your organizational unit?
  [Unknown]:  test.local.jans.io
What is the name of your organization?
  [Unknown]:  local.jans.io                                                         
What is the name of your City or Locality?
  [Unknown]:  <short name of your city>
What is the name of your State or Province?
  [Unknown]:  <short name of your state>
What is the two-letter country code for this unit?
  [Unknown]:  <short name of your country>



Warning:
The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format using "keytool -importkeystore -srckeystore /tmp/keystore.test.local.jans.io.jks -destkeystore /tmp/keystore.test.local.jans.io.jks -deststoretype pkcs12".

Above command will create a .jks file under /tmp/.

Next, we will make changes in Jetty configuration to use the keystore.

setup java web keys

Update keystore secret in database config
select JansConfDyn gluudbtest.jansAppConf where Doc_id="jans-auth"
Update JSON Web keys in database config
SELECT jansConfWebKeys FROM gluudbtest.jansAppConf where doc_id = "jans-auth";

Build and Deploy

cd auth-server-code-dir

mvn -DskipTests install

This will create a .war file which we will use to deploy.

Run Tests

Janssen integration tests need a Janssen server to execute successfully. Now that you have a Janssen instance running on your local machine, you can use it to run tests. We need to give our local workspace all the essential information about target Janssen server. This is configured in form of profile. Steps below will help us create profile in our local code workspace (auth-server-code-dir).

Create profile for client module

Create profile for server module