diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c138262..a7516b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,61 +4,22 @@ layout: default # Join the community -* Chat: We have an active [community chat on Gitter](https://gitter.im/JanssenProject/Lobby). You can register for free their with your Github identity. -* Tweet: Janssen is on [Twitter](https://twitter.com/janssen_project) too. Follow us there to stay up to date on release announcements and news around Janssen. -* Email: We have an active mailing list also. -* Google group : You can subscribe to the [Janssen Google Group](https://groups.google.com/u/2/g/janssen_project) +* **Chat**: We have an active [community chat on Gitter](https://gitter.im/JanssenProject/Lobby). You can register for free their with your Github identity. +* **Tweet**: Janssen is on [Twitter](https://twitter.com/janssen_project) too. Follow us there to stay up to date on release announcements and news around Janssen. +* **Email**: We have an active mailing list also. +* **Google group** : You can subscribe to the [Janssen Google Group](https://groups.google.com/u/2/g/janssen_project) and post messages there. # Contribute -Please go through our [contribution guidelines](#contribution-guidelines) so it'll be easy for you to make successful contributions. +Please go through Janssen [contribution guidelines](#contribution-guidelines) so it'll be easy for you to make successful contributions. -In case you are _**first-time**_ contributor, then you can start with our [good first issues list](https://github.com/JanssenProject/home/labels/good%20first%20issue) These are issues where you can easily contribute and community members will guide and support your contribution as always. +In case you are _**first-time**_ contributor, then you can start with Janssen [good first issues list](https://github.com/JanssenProject/home/labels/good%20first%20issue) These are issues where you can easily contribute and community members will guide and support your contribution as always. -If you need Janssen installation to test out your fix, here are the [steps](#janssen-quick-install). +Janssen [workspace setup guide](development.md) will help you setup your workspace where you can build and test your code changes. There are many ways of contributing to Janssen. And it is not just limited to fixing issues and raising pull requests. Janssen welcomes you to [raise issues](#issues), respond to queries, suggest new features, tell us your experience with Janssen, be it good or bad. All these are contributions towards making Janssen better. -# Janssen quick install - -Try first, ask questions later? Here's how to deploy Janssen - -## Option 1: Cloud Native with microk8s - -Start a fresh ubuntu `18.04` or `20.04` and execute the following - - ``` - sudo su - - wget https://raw.githubusercontent.com/JanssenProject/jans-cloud-native/master/automation/startdemo.sh && chmod u+x startdemo.sh && ./startdemo.sh - ``` - -This will install docker, microk8s, helm and Janssen with the default settings can be found inside [values.yaml](https://github.com/JanssenProject/jans-cloud-native/blob/master/charts/jans/values.yaml). Please map the `ip` of the instance running ubuntu to `demoexample.jans.io` and then access the endpoints at your browser such in the example in the table below. Also see [instructions for Amazon EKS](https://janssenproject.github.io/jans-cloud-native/charts/jans/) - -|Service | Example endpoint | -|------------------|------------------------------------------------------------------------| -|Auth server | `https://demoexample.jans.io/.well-known/openid-configuration` | -|fido2 | `https://demoexample.jans.io/.well-known/fido2-configuration` | -|scim | `https://demoexample.jans.io/.well-known/scim-configuration` | - - -## Option 2: VM installation - -To install: - -``` -# curl https://raw.githubusercontent.com/JanssenProject/jans-setup/master/install.py > install.py -# python3 install.py -``` - -To uninstall, run the script again with the `-uninstall` argument: - -``` -# python3 install.py -uninstall -``` - -## Option 3: You can [build jans-auth server](./development.md). - # Contribution guidelines @@ -73,7 +34,6 @@ We are really glad you are reading this, because we need volunteer developers to - [Commit convention](#commit-convention) - [Rule type](#rule-type) - [Coding Guidelines](#coding-guidelines) - - [C++](#c) - [Developer Certificate Of Origin](#developer-certificate-of-origin) ## Code of Conduct @@ -92,15 +52,30 @@ We also run monthly **community calls** which are open calls to discuss Janssen ## Issues -There are four kinds of issues you can open: +There are different kinds of issues you can open: + +- **Bug report**: + + You believe you found a problem in a project and you want to discuss and get it fixed, + creating an issue this type is the best way to do so. + +- **Development item**: + + This type of issue provides tracking mechanism for development effort. It should be opened by developers who want to contribute code to Janssen. It has checklist driven approach that helps developers make high-quality contributions. -- Bug report: you believe you found a problem in a project and you want to discuss and get it fixed, - creating an issue with the **bug report template** is the best way to do so. -- Enhancement: any kind of new feature need to be discussed in this kind of issue, do you want a new rule or a new feature? This is the kind of issue you want to open. Be very good at explaining your intent, it's always important that others can understand what you mean in order to discuss, be open and collaborative in letting others help you getting this done! -- Vulnerability: If you identify a security problem, please report it immediately, providing details about the nature, and if applicable, how to reproduce it. If you want to report an issue privately, you can email security@gluu.org -- Failing tests: you noticed a flaky test or a problem with a build? This is the kind of issue to triage that! +- **Feature request**: -The best way to get **involved** in the project is through issues, you can help in many ways: + Any kind of new feature need to be discussed. do you want a new rule or a new feature? This is the kind of issue you want to open. Be very good at explaining your intent, it's always important that others can understand what you mean in order to discuss, be open and collaborative in letting others help you getting this done! + +- **Failing tests**: + + You noticed a flaky test or a problem with a build? This is the kind of issue to triage that! + +- **Report a security vulnerability**: + + If you find a security vulnerability, please share it with Janssen team by following steps as mentioned in [Janssen security policy](https://github.com/JanssenProject/.github/blob/main/SECURITY.md#security-policy). + +The best way to get **involved** is through issues. Here you can help in many ways: - Issues triaging: participating in the discussion and adding details to open issues is always a good thing, sometimes issues need to be verified, you could be the one writing a test case to fix a bug! @@ -128,7 +103,7 @@ These guidelines are not set in stone and are subject to change. Anyway a `kind/*` label for any issue is mandatory. -This is the current [label set](https://github.com/falcosecurity/falco/labels) we have. +This is the current [label set](https://github.com/JanssenProject/home/labels) we have. You can use commands - eg., `/label ` to add (or remove) labels or manually do it. @@ -211,6 +186,3 @@ Git even has a `-s` command line option to append this automatically to your com $ git commit -s -m 'This is my commit message' ``` - -# Reference links - diff --git a/README.md b/README.md index ca7eeee..f7001f0 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,29 @@ Janssen enables organizations to build a scalable centralized authentication and authorization service using free open source software. The components of the project today include implementations of the OAuth, OpenID Connect and FIDO standards. New components may be added as the technology evolves. -# Quick links +# Get started with quick install -- [Contributing](CONTRIBUTING.md) -- [Documentation](https://ossdhaval.github.io/docs/) +Start a fresh ubuntu `18.04` or `20.04` and execute the following + + ``` + sudo su - + wget https://raw.githubusercontent.com/JanssenProject/jans-cloud-native/master/automation/startdemo.sh && chmod u+x startdemo.sh && ./startdemo.sh + ``` + +This will install docker, microk8s, helm and Janssen with the default settings can be found inside [values.yaml](https://github.com/JanssenProject/jans-cloud-native/blob/master/charts/jans/values.yaml). Please map the `ip` of the instance running ubuntu to `demoexample.jans.io` and then access the endpoints at your browser such in the example in the table below. Also see [instructions for Amazon EKS](https://janssenproject.github.io/jans-cloud-native/charts/jans/) + +|Service | Example endpoint | +|------------------|------------------------------------------------------------------------| +|Auth server | `https://demoexample.jans.io/.well-known/openid-configuration` | +|fido2 | `https://demoexample.jans.io/.well-known/fido2-configuration` | +|scim | `https://demoexample.jans.io/.well-known/scim-configuration` | + +What you just installed is Cloud Native Janssen with microk8s. Explore [different ways](https://janssenproject.github.io/docs/source/installation-guide/) to install and deploy Janssen to suite you needs in production. + +# Get to know Janssen + +Learn more and in-depth about Janssen features and module using [documentation](https://janssenproject.github.io/docs/) + +# Contribute + +Want to contribute? Our [Contribution](CONTRIBUTING.md) guide will get you started diff --git a/development.md b/development.md index b345327..4456559 100644 --- a/development.md +++ b/development.md @@ -1,209 +1,525 @@ -# Setting up Janssen development environment -## Overview +# Setting up workspace for Janssen development -This is a generic guide for setting up a development environment that enables compilation and testing of Janssen components. For a complete development environment, you need three things: +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. -1) Janssen server for development -2) Workspace which has code and tests that you can run -3) Ability to remote debug +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](TODO). -In this guide, we will see how to setup both. You can setup both on same machine or on different machines. +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. -## Installing Janssen server: +- [Pre-Requisites](#pre-requisites) +- [Get Code](#get-code) +- [Setup Data Store](#setup-data-store) +- [Setup Configuration Files](#setup-configuration-files) +- [Setup SSL](#setup-ssl) +- [Build and Deploy](#build-and-deploy) +- [Run Tests](#run-tests) -When you plan to develop and contribute code to Janssen, you need a running Janssen server in order to run your tests and verify that your feature or bug fix is working as intended. You can plan to install Janssen server on local Windows machine, Linux machine or you may planning to install Janssen using Janssen cloud based deployment. +## Pre-requisites -### Hardware requirements of Janssen server +### Download and Install required software -- 8 GB RAM for Janssen server installation -- CPU with at least two cores -- 40 GB harddisk space +##### JDK -### Platform requirements of Janssen server +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](https://docs.aws.amazon.com/corretto/latest/corretto-11-ug/downloads-list.html). + + +##### Git -Janssen auth server installs on Linux based operating system, primarily, Ubuntu. If your development environment is using a different operating system, like Windows, we have to leverage virtualization tools to install Janssen server. Follow the instructions listed in sections below as appropriate. +Janssen code is hosted on Github. You can use any Git client to interact with +repositories. + -1) [On Windows OS](https://github.com/ossdhaval/home/blob/main/development.md#installing-janssen-auth-server-on-windows-machine) -2) [On Ubuntu 20.4](https://github.com/ossdhaval/home/blob/main/development.md#install-janssen) -3) [On remote server](https://github.com/ossdhaval/home/blob/main/development.md#installing-janssen-auth-server-on-remote-server) ( like a Google Cloud Platform or AWS Linux instance ) -4) On Cloud based deployment +##### Maven -### Installing Janssen auth server on Windows machine +Maven is a build tool used by Janssen. You can download it from [here](https://maven.apache.org/download.cgi) -Janssen runs on Linux based operating system Ubuntu. In order to run it on a Windows machine, we have to leverage virtualization technique as described in steps below. -#### Prepare your Windows machine +##### MySQL -Steps: +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](https://www.mysql.com/downloads/) + - 1) `TODO` - 2) `TODO` +##### Jetty server -Once you have executed above steps, your Windows machine is ready for [Janssen installation](https://github.com/ossdhaval/home/blob/main/development.md#install-janssen). +Janssen uses Jetty as web application server. You can download and +install Jetty 9 from [here](https://www.eclipse.org/jetty/download.php). -### Installing Janssen auth server on remote server +### Setup environment variables -If you have limited hardware resources on your local machine, then you may install Janssen on a remote server. For this you need to have access to a remote server, either standalone or an instance hosted on any cloud platform like GCP or AWS. Here in this guide, we will take example of installing Janssen server on an GCP instance. +- `JAVA_HOME`: This should be set so that it points to your JDK installation directory +- `JETTY_HOME`: This is the directory where you have installed or unpacked your + jetty distribution. This directory should contain `start.jar` + so that `$JETTY_HOME/start.jar` is accessible. +- `JETTY_BASE`: Set this variable by creating an empty directory + where you intend to deploy Janssen auth server web application +- Host name: For Janssen modules to work correctly, you need to assign a + host name to your local machine's IP. `localhost` is not + supported. To do this, we need to make changes to `hosts` file. On Ubuntu + and other Linux destributions, this file is `/etc/hosts`, while for Windows + same file can be found at `C:\Windows\System32\drivers\etc\hosts`. Make an + entry similar to below in `hosts` file: + + ``` + 127.0.0.1 test.local.jans.io + ``` + + Here, `test.local.jans.io` can be any name of your choice. We will refer to +`test.local.jans.io` as our host name for rest of this guide. -#### Prepare GCP instance +- Before we start, we need to initialize few Jetty modules as shown below: -Steps: + ``` + cd $JETTY_BASE + + java -jar $JETTY_HOME/start.jar --create-startd + + java -jar $JETTY_HOME/start.jar --add-to-start=server,annotations,resources,http-forwarded,threadpool,console-capture,jsp,websocket,https,ssl + ``` - 1) `TODO` - 2) `TODO` +## Get code -Once you have executed above steps, your GCP instance is ready for [Janssen installation](https://github.com/ossdhaval/home/blob/main/development.md#install-janssen). +- JanssenProject code is hosted on Github. You can find it [here](https://github.com/JanssenProject). + Project has multiple repositories for various modules. This guide will take us + through setup of Janssen Auth server module. For this, you need to clone repositories + listed below: + + - [jans_setup](https://github.com/JanssenProject/jans-setup) (local clone location will be referred to as `setup-code-dir` going forward) + + - [jans-auth-sever](https://github.com/JanssenProject/jans-auth-server) (local clone location will be referred to as `auth-server-code-dir` going forward) + + Compile and package code locally as + + ``` + cd auth-server-code-dir -## Install Janssen + mvn -DskipTests package + ``` + + Above should compile code successfully and also create files in `target` folder under `auth-server-code-dir`. Some of these files will be helpful to us in next steps. + +## Setup data store -Janssen installation involves running two commands. During installation, setup will prompt few questions and you'll also need to accept license. During this process, among other inputs, the setup will also ask you to name your Janssen server. You can name it anyting but make note of it, as we will need that name in future. For now, we will assume that server is named *demoexample.jans.io*. +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. -First command to run is as below. It'll download required installation script. +As a first step, let's create schema and users. -`wget https://raw.githubusercontent.com/JanssenProject/jans-setup/master/install.py` +- Log into MySQL using `root` user (or any other user with sufficient privileges) -Once you have the script, you can start installation. You can either start installation with or without test data loading along with it. Test data load will help you to run unit tests when you are writing code. You can also choose to load it later when needed. + ``` + sudo mysql root + ``` + +- Create new database(schema) for Janssen -To install with test data load: + ``` + mysql> CREATE DATABASE jansdb; + ``` + +- Create new db user -`sudo python3 install.py –args="-t"` + ``` + CREATE USER 'jans'@'localhost' IDENTIFIED BY 'PassOfYourChoice'; + ``` + +- Grant privileges to new user on `jans` schema + + ``` + GRANT ALL PRIVILEGES ON jansdb.* TO 'jans'@'localhost'; + ``` + +- Exit MySQL login -To install without test data load: +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. -`sudo python3 install.py` +- Get MySQL database data load script file from [here](TODO add link here). This +script is a data dump which can directly be loaded in your local MySQL database. But + before we load it, we need to replace generic host name in the script with the one + that we have set for our local environment, which is `test.local.jans.io`. To do + that, open script in a text editor and + + - replace string `https://testmysql.dd.jans.io` with `https://test.local.jans.io:8443` + + - replace string `testmysql.dd.jans.io` with `test.local.jans.io` -Load test data separately from installation process: +- Script is now ready to be executed. +- Import data load script into your local MySQL + + ``` + sudo mysql -u root -p < jansdb_dump.sql + ``` + + +## 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 ``` -cd /opt/jans/jans-setup/ -sudo python3 setup.py -t -x -n + + + ``` +mkdir $JETTY_BASE/custom -After successful execution, you have a working Janssen setup. +mkdir $JETTY_BASE/custom/pages +``` -Now, to access Janssen end-points, please map `IP` address of your Janssen server with name of Janssen server which you provided during install process. This mapping needs to be in `/etc/hosts` file of host from where you intend to access the end-point URLs. Once this mapping is done, you can access below mentioned end-points to verify your Janssen installation: +Now, we need to copy teplates of these configuration files from our code base. +``` +sudo cp /server/target/conf/* /etc/jans/conf/ +``` - |Service | Example endpoint | - |------------------|------------------------------------------------------------------------| - |Auth server | `https://demoexample.jans.io/.well-known/openid-configuration` | - |fido2 | `https://demoexample.jans.io/.well-known/fido2-configuration` | - |scim | `https://demoexample.jans.io/.well-known/scim-configuration` | +Among copied files, there are two files that are notable: + - `jans.properties`: Holds details like type of persistance to use, localtion of certificates etc. + - `jans-sql.properties`: Since we are using MySQL RDBMS persistence store, + details in this file will be used to connect MySQL. +Edit values in both these files as recommended below. -## Setup your workspace +``` +sudo vim /etc/jans/conf/jans.properties +``` -#### Minimal software requirements + - edit `persistence.type: ldap` to `persistence.type: sql` + - edit `certsDir` to `certsDir=/etc/jans/conf` `todo: change this to /etc/certs` + - edit value of `jansAuth_ConfigurationEntryDN` to `jansAuth_ConfigurationEntryDN=ou=jans-auth,ou=configuration,o=jans` so that it matches `jans-auth` entry in `jansAppConf` table in DB `todo: add more entries here for each module added in jans installation like scim etc` -Most basic tools required are -- `git` : To clone and manage the inav code repository -- `java` : Java to run maven and build. Needs Java 1.8 or above -- `mvn` : latest maven -- Other tools like IDE etc can be of your choice +``` +sudo vim /etc/jans/conf/jans-sql.properties +``` + + - Set `db.schema.name` to name of schema you created while importing data load script. + - Set `connection.uri` to `jdbc:mysql://localhost:3306/jansdb` + - Set `auth.userName` to the new user that we created above, i.e `jans` + - Set `auth.userPassword` to passwod that you set while creating new user, i.e `PassOfYourChoice` + - Set `password.encryption.method` to method you have selected to encrypt the password for `userPassword` property. If you are using plain text password for your local setup, comment out this property. + + 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 -Setting up your workspace is as easy as cloning Janssen module repository from Github. You can clone the repository of the module that you intend to work on. +# Password hash method +password.encryption.method=SSHA-256 -Here, we are going ahead with Janssen auth server module. +# Connection pool size +connection.pool.max-total=40 +connection.pool.max-idle=15 +connection.pool.min-idle=5 -#### Get code +# Max time needed to create connection pool in milliseconds +connection.pool.create-max-wait-time-millis=20000 -You can get code for Janssen modules from Github repository [here](https://github.com/JanssenProject) +# Max wait 20 seconds +connection.pool.max-wait-time-millis=20000 -In the directory where you want to create your workspace, you can clone the module as below: +# Allow to evict connection in pool after 30 minutes +connection.pool.min-evictable-idle-time-millis=1800000 -`git clone https://github.com/JanssenProject/jans-auth-server` +binaryAttributes=objectGUID +certificateAttributes=userCertificate -#### Build +``` -`cd jans-auth-server` +## Setup SSL -At this point, you should be able to successfully compile the module using `mvn compile` +Janssen uses secure socket layer (SSL) to secure HTTP communication. To enable +same of our local setup, we need to configure self signed ceritificates. -#### Run tests +- We will use Java keytool to generate key pair as given below. + +``` -In order to be able to run tests, your code in your local workspace should be able to connect to Janssen server that you installed previously. This is done by creating a `profile` and a few more commands. That is what we will do next. +keytool -genkeypair -alias jetty -keyalg EC -groupname secp256r1 -keypass secret -validity 3700 -storetype JKS -keystore /tmp/keystore.test.local.jans.io.jks -storepass secret -##### Create test profile +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]: +What is the name of your State or Province? + [Unknown]: +What is the two-letter country code for this unit? + [Unknown]: -###### What is a profile: -At the most basic level, a profile is a directory, with the same name as your server and contains files that enable your code to connect with Janssen server. In following steps, We will create profile directory where your code is and put required files under it. During it's installation, the Janssen server has already created these files for us to copy. -1) Get profile name which we will be using. Run this command where Janssen server is installated. +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". -`cat /opt/jans/jans-setup/output/test/jans-auth/client/config-oxauth-test-data.properties | grep clientKeyStoreFile | cut -d "/" -f2 | cut -d "/" -f1` +``` - Output of this command is the profile name that you need to use in following steps. Generally, this name is same as name of your Janssen server. +Above command will create a `.jks` file under `/tmp/`. -2) Create and setup your profile - - Setup profile for *client* module of *jans-auth-server* - - `mkdir ./client/profiles//` - - `cp -rf /opt/jans/jans-setup/output/test/jans-auth/client/* ./client/profiles//` - - `cp ./client/profiles/default/client_keystore.jks ./client/profiles//` - - Setup profile for *server* module of *jans-auth-server* - - `mkdir ./server/profiles//` - - `cp -rf /opt/jans/jans-setup/output/test/jans-auth/server/* ./server/profiles//` - - `cp ./server/profiles/default/client_keystore.jks ./server/profiles//` +Next, we will make changes in Jetty configuration to use the keystore. -If your code and installed Janssen server is on the same machine, then at this point you should be able to [run full build](https://github.com/ossdhaval/home/blob/main/development.md#run-full-build-with-tests) with tests. If both are on separate machines then you need to take [few additional steps](https://github.com/ossdhaval/home/blob/main/development.md#additional-steps-for-remote-workspace) before you can run your full build with tests. + - copy your keystore file which you generated above to `$JETTY_BASE/etc/` + + ``` + cp /tmp/keystore.test.local.jans.io.jks $JETTY_BASE/etc/ + ``` -##### Additional steps for remote workspace + - Now edit `ssl.ini` and change value of below properties + + ``` + vim $JETTY_BASE/start.d/ssl.ini + ``` -These steps are only needed if we need to run build and tests on a different machine then the one where you have installed Janssen server. Also its not needed if we deploy CA cert into Janssen instalation. + + Uncomment and apply appropriate values to properties below according to inputs that you gave during creation of keystore. + + + ``` + jetty.sslContext.keyStorePath=etc/keystore.test.local.jans.io.jks + jetty.sslContext.keyStorePassword=secret + jetty.sslContext.trustStorePath=etc/keystore.test.local.jans.io.jks + jetty.sslContext.trustStorePassword=secret + jetty.sslContext.keyManagerPassword=secret + ``` + +- Add more keys to keystore. These keys are required for running tests. When asked, the password for source keystore is `secret`. + + ``` + keytool -importkeystore -srckeystore /jans-auth-server/server/profiles/default/client_keystore.jks -destkeystore /tmp/keystore.test.local.jans.io.jks + ``` + +- Generate JWT + + - download `jans-auth-client-1.0.0-SNAPSHOT-jar-with-dependencies.jar` from `https://maven.jans.io/maven/io/jans/jans-auth-client/1.0.0-SNAPSHOT/` + - change to download location + + ``` + cd + ``` + + - now run + + ``` + java -Dlog4j.defaultInitOverride=true -cp jans-auth-client-1.0.0-SNAPSHOT-jar-with-dependencies.jar io.jans.as.client.util.KeyGenerator -keystore '/tmp/keystore.test.local.jans.io.jks' -keypasswd secret -sig_keys RS256 RS384 RS512 ES256 ES384 ES512 -enc_keys RS256 RS384 RS512 ES256 ES384 ES512 -dnname 'CN=Jans Auth CA Certificates' -expiration 365 > /tmp/keys_client_keystore.json + ``` + + This command adds additional keys in `keystore.test.local.jans.io.jks` and creates a JSON file with web keys. We will use web keys files later to update db entries. + +- Provide keystore to Janssen and your code base from where the tests are going to get executed + + - copy keystore file to profiles in `client`, `server` modules in code base `TODO: see if this step is required as we are now adding certs in cacerts` + - Client: + + ``` + mkdir /client/profiles/test.local.jans.io + + cp /tmp/keystore.test.local.jans.io.jks /client/profiles/test.local.jans.io/ + ``` + + - Server: + + ``` + mkdir /server/profiles/test.local.jans.io + + cp /tmp/keystore.test.local.jans.io.jks /server/profiles/test.local.jans.io/ + ``` + + - Copy keystore to Janssen + + ``` + sudo mkdir /etc/certs + + sudo cp /tmp/keystore.test.local.jans.io.jks /etc/certs/jans-auth-keys.jks + + sudo chown : /etc/certs/jans-auth-keys.jks + ``` + +- Update your Java cacerts + + - extract certificate + + ``` + openssl s_client -connect test.local.jans.io:8443 2>&1 |sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/httpd.crt + ``` + + - Update cacerts of your JRE. For example if JRE being used my maven is `/usr/lib/jvm/java-11-openjdk-amd64` + + ``` + keytool -import -alias jetty -keystore /usr/lib/jvm/java-11-openjdk-amd64/lib/security/cacerts -file /tmp/httpd.crt + ``` -1) Import self signed http cert into java truststore. +### setup java web keys -Copy `/etc/certs/httpd.crt` from CE server to `/httpd.crt` or run: +##### Update keystore secret in database config -`openssl s_client -connect :443 2>&1 |sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/httpd.crt` +- update value of keystore secret in DB under entry -`/opt/jre/bin/keytool -import -alias jans_http -keystore /opt/jre/lib/security/cacerts -file /tmp/httpd.crt` +``` +select JansConfDyn gluudbtest.jansAppConf where Doc_id="jans-auth" +``` +##### Update JSON Web keys in database config -2) Fill the right configuration `cibaEndUserNotificationConfig`. It's in `jansConfDyn` in ou=jans-auth,ou=configuration,o=jans. After restart Jans Auth server: +- open `/tmp/keys_client_keystore.json` and copy content into db field ``` -systemctl restart jans-auth +SELECT jansConfWebKeys FROM gluudbtest.jansAppConf where doc_id = "jans-auth"; ``` -##### Run full build with tests: +## Build and Deploy ``` -mvn -fae -Dcfg= -Dcvss-score=9 -Dfindbugs.skip=true -Ddependency.check=false clean compile package +cd auth-server-code-dir + +mvn -DskipTests install ``` + +This will create a `.war` file which we will use to deploy. + +- Move and rename war -You should be able to run test cases successfully. + ``` + mv server/target/jans-auth-server.war $JETTY_BASE/webapps/jans-auth.war + ``` -## Setup remote debugging +- Get template xml files from setup repo -#### Changes required on Janssen server + ``` + cp /templates/jetty/jans-auth.xml $JETTY_BASE/webapps/ + + cp /templates/jetty/jans-auth_web_resources.xml $JETTY_BASE/webapps/ + ``` -- Open service config file +- Now we can run Janssen auth server: - `vim /etc/default/jans-auth` + ``` + $ java -Djetty.home=$JETTY_HOME -Djetty.base=$JETTY_BASE -Dlog.base=/home/dhaval/temp/jetty-logs -Djans.base=/etc/jans -Dserver.base=$JETTY_BASE -jar $JETTY_HOME/start.jar + ``` -- add line below at the end of `JAVA_OPTIONS` - `-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=6001` +## Run Tests -- then restart services +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`). - `systemctl restart jans-auth.service` - -- (only if you are using GCP instance as jans server) add port to firewall: - - search for firewall on dashboard search - - edit the firewall called `default-allow-ssh`, and add port `6001`. Save settings. - - not sure but you may want to restart your instance once for firewall settings to take effect. +#### Create profile for `client` module -#### changes required in the machine where your workspace is: +- Create profile directory for client module -- setup port forwarding + ``` + mkdir auth-server-code-dir/client/profiles/test.local.jans.io + ``` - `ssh -L 6001:localhost:6001 @demoexample.jans.io` +- copy contents of default profile to new profile directory + + ``` + cp /client/profiles/default/* /client/profiles/test.local.jans.io/ + ``` + +- Customize the values as per your setup - this command will open an ssl connection with jans server. Keep the window open. + ``` + cd /client/profiles/test.local.jans.io/ + ``` + - In file `config-oxauth-test-data.properties` update values of `test.server.name` and `swd.resource` properties with your host name. i.e `test.local.jans.io` and update path in `clientKeyStoreFile` property with `profiles/test.local.jans.io/client_keystore.jks` + +#### Create profile for `server` module + +- create profile directory for server module + + ``` + mkdir /server/profiles/test.local.jans.io + ``` +- copy contents of default profile to new profile directory + + ``` + cp /server/profiles/default/* /server/profiles/test.local.jans.io/ + ``` +- Customize the values as per your setup + + ``` + cd /server/profiles/test.local.jans.io/ + ``` -- In IntellijIdea, - - `shift+shift` -> search for `edit configuration` -> click on `+` -> `remote jvm debugging` -> then give below values - - `host:` remote host IP or name as in `hosts` file, `port:` 6001, `use module:` give the module which is being debugged on server. - + - Edit config-oxauth.properties + - Update values of `server.name`,`config.jans-auth.issuer`,`config.jans-auth.contextPath` properties to your host name + - comment out the properties for LDAP + - Edit config-oxauth-test.properties + - By default, this file contains properties applicable to LDAP backend. But since we are using MySQL as backend, we will remove all the current properties in this file and put properties listed below in it: + + ``` + server.name=test.local.jans.io + config.oxauth.issuer=http://localhost:80 + config.oxauth.contextPath=http://localhost:80 + config.persistence.type=sql + + #sql + + config.sql.db.schema.name= + config.sql.connection.uri=jdbc:mysql://:3306/ + config.sql.auth.userName= + config.sql.auth.userPassword= + config.sql.connection.driver-property.serverTimezone=UTC + config.sql.password.encryption.method= + config.sql.auth.userName= + config.sql.auth.userPassword= + + # Password hash method + config.sql.password.encryption.method=SSHA-256 + + # Connection pool size + config.sql.connection.pool.max-total=20 + config.sql.connection.pool.max-idle=10 + config.sql.connection.pool.min-idle=5 + + # Max time needed to create connection pool in milliseconds + config.sql.connection.pool.create-max-wait-time-millis=20000 + + # Max wait 20 seconds + config.sql.connection.pool.max-wait-time-millis=20000 + + # Allow to evict connection in pool after 30 minutes + config.sql.connection.pool.min-evictable-idle-time-millis=1800000 + + ``` + + - Edit config-oxauth-test-data.properties and update values of below properties: + + ``` + test.server.name=test.local.jans.io + test.server.url=https://test.local.jans.io:8443/jans-auth + + clientKeyStoreFile=profiles/test.local.jans.io/keystore.test.local.jans.io.jks + clientKeyStoreSecret=secret + + ``` + + +- Now you can run test cases for each module with + + ``` + mvn -Dcfg=test.dd.jans.io -fae -Dcvss-score=9 -Dfindbugs.skip=true -Dlog4j.default.log.level=TRACE -Ddependency.check=false clean test + ```