Steps to Setup On-Premise IDP

Step 1: Installation and Initial Setup

• This short tutorial walks you through starting up the server in standalone mode, setting up the initial admin account, and logging into the miniOrange admin dashboard.
• Pre-Requisites:

• Java 8 (JDK 1.8): When you install JAVA 8, only JRE 1.8 would be present.

  Note: Tomcat is already included in this distribution (zip file), you don’t have to install it separately.

  For Windows User - Installation of JDK 1.8 requires login through the oracle account. If you don't have the oracle account, you can directly install JDK 1.8 from here.

  For Linux Users - You can download OpenJDK8 package using apt install openjdk-8-jdk for Debian, Ubuntu, etc. OR yum install java-1.8.0-openjdk for Fedora, Oracle Linux, Red Hat Enterprise Linux, etc.

• If JAVA is already installed and Environment Varibles are set correcty on your system, then you dont need to follow this step, you can directly go to step 1.2.

  Note - Once the Java installation is complete, check that the JAVA_HOME environment variable has been set correctly.Open a command prompt and type echo %JAVA_HOME% and hit Enter. If you see a path to your Java installation directory, the JAVA_Home environment variable has been set correctly.If nothing is displayed, or only %JAVA_HOME% is returned, you'll need to set the JAVA_HOME environment variable manually.

  For Windows User - Set Java environment variables i.e. JAVA_HOME and JRE_HOME and path variables. Lets say JDK software is installed on your computer, for example, at C:\Program Files\Java\jdk1.8.0_221 then JAVA_HOME and JRE_HOME paths can be as mentioned -

  • JAVA_HOME - C:\Program Files\Java\jdk1.8.0_221
  • JRE_HOME - C:\Program Files\Java\jdk1.8.0_221\jre

  To Save these variables, right click My Computer and select Properties > Advanced System Settings.Click the Environment Variables button.Under System Variables, click New.In the Variable Name field, enter:

  • JAVA_HOME - C:\Program Files\Java\jdk1.8.0_221
  • JRE_HOME - C:\Program Files\Java\jdk1.8.0_221\jre
  Also update the path variable set with path : path_to_JAVA_HOME/bin. You can Read more about java specfic environment variables.

  For Linux Users- Linux users can use below commands to set JAVA_HOME and JRE_HOME variables using below commands -

  1. export JAVA_HOME=/path/to/jdk
  2. export JRE_HOME=/path/to/jre

• You can verify whether above environment variables are set correctly. Execute below commands to verify environment variables -

  1. echo $JAVA_HOME
  2. echo $JRE_HOME

Step 1.2: Installing On-Premise Server

• To start the miniOrange server, go to the bin/ directory of the server distribution (i.e. folder with name similar to mo-idp-server-1.0.3 (version may vary)). Execute the startup file based on your environment.
• Linux/Unix – Execute chmod +x startup.sh to give executable permission to this file. Set relevant permission of mo-idp-server folder to allow the creation of new folder like temp or logs folder – chmod 755.
  $ .../bin/startup.sh
• Windows
  > ...\bin\startup.bat

Step 1.3: Setup Database

• After tomcat startup, open http://localhost:8080 in browser. You will see a page to choose a database configuration for the identity server. You can choose where you would like to store its data.
• miniOrange On-Premise Identity Provider gives you the flexibility to choose your database type. We support Embedded H2 Database which is a light weight database good for testing purposes. Later you can migrate to your production database type that is supported in the external database section. In External Database section, we support Postgresql (ideally 9.6), MySql and Oracle Databases.

  Setup Embedded Database

• Note : Before you proceed with Embedded H2 database, make sure your system has given write permission to the IdP folder i.e. mo-idp-server- folder. If not then first assign the write permission to the IdP folder to avoid getting stuck in permission issues. Write permission is required because Embedded H2 database is created in IdP folder with the folder named data.
• Select embedded Database and click on proceed.

• Set up miniOrange with the embedded H2 database to get you started. You’ll need to migrate to a supported external database before using miniOrange as a production system. This option is recommended if you’re just using miniOrange for a test trial. The database folder is created inside the mo-idp-server folder named data.
• Note: In case if you are stuck in permission issues, you can run commands specific to your OS to perceed or you can follow the instructions given on pop-up.

Windows	icacls “path upto mo-idp-server-X ” /remove:d Users /grant:r Users:(OI)(CI)F /T
Linux	chmod -R 775 “path upto mo-idp-server-X”

• If you dont have enough previleges to run above commands, in that case either you can follow instructions from pop-up or can contact us.

• Once database is created successfully, you will be redirected to the admin set up page where you will configure admin account for Identity Provider.

  Setup External Database

• Set up miniOrange with the external database supported in the list below. This is recommended for production systems. miniOrange supports a number of databases and if you don’t have an established database of choice within your organization and do not have a strong preference for any of our supported databases, we recommend the PostgreSQL, which is free and thoroughly tested against.
• You can refer to the below document to see supported versions of MySQL and PostgreSQL – click here. Note: If you already have a database setup which is not in the list below. You can contact us to add support for that database.
• Create an empty database in your database server – PostgreSQL/MySQL. Once done, start filling the form shown below –

• Enter Database Host – localhost or IP address.
• Enter Database Port :
  PostGres – 5432
  MySQL – 3306
• Enter the Database Name created in your database server.
• Enter username and password of your database server for the connection.

• Once database is created successfully, you will be redirected to the admin set up page where you will configure admin account for Identity Provider.

Step 1.4: Setup Admin Account

• Setup your Admin Account. Enter a Username and Password for your admin account.

• Once your admin account is created, you will be auto logged in to the dashboard screen.

Step 2: Features

• Different features you can try out in miniOrange Identity and Authentication Server are as follows-

Single Sign On-



• Enable this module as Identity Broker – Identity Brokering allows users to authenticate using any external IDPs like ADFS, Azure AD, Shibboleth, SimpleSAMLPHP, Google Apps, etc as well as OAuth Providers like Windows Live, Slack, SafeIX, Gitlab and all Social Providers.
• Enable this module as Identity Provider – You can configure any user store like LDAP, AD, AWS Cognito and enable this module as Identity Provider to your apps. Default user store is default database shipped with the server.
• Two Factor Authentication – You can choose from various authentication methods like OTP over Email/SMS, Google Authenticator, Security Questions, Hardware Token, etc. to enable 2fa for your account.
• Adaptive Risk-Based Authentication – You can give access to different apps to your employees, users based on Device, IP, Time and Location.
• Centralized Admin Dashboard – Admin Console for central management of users, groups, group mappings, client apps, and configuration.
• User Account Management Dashboard – Access all your apps from a single dashboard. It allows users to centrally manage their account.
• Branding and Customization Support Options – Brand all your user-facing pages with your own logo, favicon, and theme. Customize all Email Templates for user registration, reset a password, user activation,otp over email, etc. You can add more than 20 custom attributes for user as well as group.

Step 3: Steps to run On-Premise IdP server over SSL

Before moving forward, you need to make two changes related to samesite cookie. Starting with version 80, Google Chrome will change the default value for the SameSite cookie parameter to Lax. Therefore, changes are required and SameSite parameter has to be set to NONE.

To do changes, follow the path: mo-idp-server >> moas >> WEB-INF >> classes. In this folder search for the file spring-context-onpemise and open it in editor. Search for bean id="customCookie". you will see a bean with name,samesite and secure properties. Update value of samesite from LAX to NONE and of secure to true.

• This document provides the steps to setup IDP server over SSL . It contains 2 sections A and B.

  Section A:

• This section provides the steps to setup IDP over self signed SSL certificate.

  Step 1: Generate a Keystore

  • Open a command prompt or terminal. And go to <Path to JAVA_HOME/bin> path and enter the command given below.
    keytool -genkey -alias onpremssoidp -keyalg RSA -keystore onpremssoidp.jks
  • If you get a permission error (mostly on a windows machine) in this step.Then change the location in command prompt or terminal to Desktop or any other location of your choice. See image in Step 2.
  • Enter your convenient password and remember it.(If the password you entered didn’t work then keep the password as “changeit” ).

  Step 2: Generate SSL Certificate

  • After Pressing the Return key it will prompt for a password for . Hit Return to continue.
    (Note: firstname and lastname needs to be the server DNS name/hostname of the server)
  
  • SSL self-signed certificate is generated at the given location.

  Step 3: Configure Tomcat with above-generated Keystore

  • Open conf\server.xml (present in tomcat folder).
  • Search for <Service name=”Catalina”> and paste the code snippet given in section 3.a in the next line of<Service name=”Catalina”>.
    1. Code snippet <Connector port="443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="<JKS Keystore Path>" ciphers="ALL" keystorePass="<Password while keystore generation>"/>
    2. Now you have SSL working on your machine. Follow the steps below if you want to set up the branding. If you don’t want to setup the branding then ignore the steps below and start your tomcat.

  Part B: Using a certificate from Trusted CAs like LetsEncrypt, GoDaddy, Comodo SSL.

  a) LetsEncrypt

  • The following steps assume that you have a valid certificate generated through Certbot. In case you do not have the certificates, you can use the Certbot commands below to generate the certificate for your domain
  • certbot certonly --standalone -d.example.com
  • Once the certificate is generated, the following folder structure will be obtained.
  • #:/etc/letsencrypt/live/example.com# ls
cert.pem chain.pem fullchain.pem privkey.pem README
  • Copy over the cert.pem, chain.pem, fullchain.pem and privkey.pem in the conf directory of the IdP.
  • Edit the conf/server.xml and add the following connector element.

  •  <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
                                                          maxThreads="150" SSLEnabled="true">
                                                          <SSLHostConfig>
                                                          <Certificate certificateFile="conf/cert.pem"
                                                                          certificateKeyFile="conf/privkey.pem"
                                                                          certificateChainFile="conf/chain.pem" />
                                                                          <SSLHostConfig>
                                                                          <Connector>
                                                      

  • Restart the IdP. The IdP should now use the valid certificate from LetsEncrypt.

  b) Go Daddy

  • The steps below assume that you have downloaded the valid SSL certificates from GoDaddy. The certificates need to be imported in a Java Keystore (JKS). In order to create a JKS, the keytool utility can be used.
  • keytool -genkey -alias onpremssoidp -keyalg RSA -keystore onpremssoidp.jks
  • The original certificates need to be removed from the keystore. That can be done using the below command.
  • keytool -delete -alias onpremssoidp -keystore onpremssoidp.jks
  • OpenSSL commands can be used to import the certificates downloaded from GoDaddy into the Java Keystore.
  • openssl pkcs12 -export -in .crt -inkey .key -out .p12 -name tomcat -CAfile gd_bundle-g2-g1.crt -caname root
  • The keystore can now be used to configure the connector in conf/server.xml.

  • <Connector port="443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true"
                                                      clientAuth="false" sslProtocol="TLS" keystoreFile="<JKS Keystore Path>" ciphers="ALL"
                                                      keystorePass="<Password while keystore generation>"/>
                                                      

  • Restart the IdP. The IdP should now use the valid certificate from GoDaddy.

  c) Comodo SSL

  Creating a New Keystore

  • Navigate to the directory where you plan to locate the new keystore.
  • Enter the following command:
  • keytool -genkey -alias server -keyalg RSA -keysize 2048 -keystore your_site_name.jks
  • When prompted, create a password for your new Keystore.
  • Enter the required information (Note: Do not type your own name into the name field, type your FQDN).
  • When finished, verify your information by typing “Y” or “Yes.” (Minus the period at the end.)
  • Finally, enter the password you just created in step three.
  
  

  Creating a CSR on Tomcat Servers

  • Run the following command:
  • keytool -certreq -alias server -file csr.txt -keystore your_site_name.jks
  • Once prompted, enter the password you created in step three of the Keystore instructions
  • Use the information you supplied when creating the keystore. The CSR will be generated and saved in the chosen directory as “CSR.txt.”
  • We recommend saving and backing up the keystore file once you’ve complete generating the CSR. Once you’ve got the CSR complete, choose the SSL certificate you’d like to install on your Tomcat server and then purchase it, copy/pasting the CSR (open the .txt file) into the relevant field (usually the one labelled CSR).
  • Once the purchase and validation are complete, the CA will email you a bundle that includes your SSL certificate and an intermediate certificate that needs to be installed with it.
  
  

  How to Install an SSL Certificate on Your Tomcat Server

  • Save your certificate(s) to the Keystore directory you created.
  • Use the following command to import the keystore:
  • keytool -import -alias server -file your_site_name.p7b -keystore your_site_name.jks
  • You should see a confirmation message that says: “Certificate reply was installed in keystore.”
  • Type “Y” or “Yes” to trust the certificate.
  • Now, finally, we just need to configure the Tomcat server to serve the website via HTTPS.
  
  

  Configuring Your SSL/TLS Connector

  • Using a text editor, open your Tomcat server.xml file.
  • Locate the connector you want to secure with your new keystore.
  • Configure the connector to use port 443 (HTTPS), your configuration file should look something like this:

  • <Connector port="443" maxHttpHeaderSize="8192" maxThreads="100"
                                                          minSpareThreads="25" maxSpareThreads="75"
                                                          enableLookups="false" disableUploadTimeout="true"
                                                          acceptCount="100" scheme="https" secure="true"
                                                          SSLEnabled="true" clientAuth="false"
                                                          sslProtocol="TLS" keyAlias="server"
                                                          keystoreFile="/home/user_name/your_site_name.jks"
                                                          keystorePass="your_keystore_password" />

• Save the changes to your server.xml file.
• Restart your Tomcat server.
• If the above methods dont work follow the link given below
• Click here to follow the steps if you have any other CA certificates.

Step 4: Update hostname

• Update hostnames in server.xml
• Search for localhost, wherever the localhost is mentioned in server.xml, change it to actual server name. It is there in two places.

Step 5: Add an entry in the hosts file (For branded URL)

(Follow this step if you are using self signed certificate)

• Windows: Add an entry in the %windows%\system32\drivers\etc\hosts.
• Linux : Add an entry in /etc/hosts.
• 127.0.0.1 Host with which IdP will be accessed. e.g: <brand-name>.com or <brand-name>.in .


Step 6: Add an entry in vhost file present in apache.

(Follow this step if you are using self signed certificate)

• Goto path where apache is installed.
• Open httpd-vhost in some editor (notepad++).
• In Linux, it is mostly present in /etc/apache2/etc/apache2/sites-available/.
• In Windows, it is present in xampp/apache/conf/extra/.
• If you can't find the apache location on the paths given above, then either apache is not installed or it is present in a different directory.
• Add the snippet below to the end of the file.
• Ensure all the paths are replaced properly in the snippet. The server.crt and server.key are provided by apache itself in the repective folders in conf. You can also provide path for your own certificate and key.
<VirtualHost *:443> DocumentRoot "path upto the moas folder" ServerName [your-domain-name].com ServerAlias www.[your-domain-name].com ProxyPreserveHost On ProxyPass /moas https://localhost:443/moas ProxyPassReverse /moas https://localhost:443/moas SSLEngine on SSLProxyEngine on SSLCertificateFile "conf/ssl.crt/server.crt" SSLCertificateKeyFile "conf/ssl.key/server.key" <Directory "Path upto moas folder"> Options Indexes FollowSymLinks AllowOverride All Order allow,deny Allow from all </Directory> </VirtualHost>  

Step 7: Modify the Server Base URL in General Product Settings in the IdP

• You should now be able to access the deployed On-Premise IdP over HTTPS.
• From miniOrange admin dashboard, go to Settings>>product settings (present on right top).
• Enter the Server base URL as shown in the image below.

Step 4: Steps to run Tomcat as a Service for OnPremise IDP

• For Windows:
• Install Tomcat as Windows Service using a Windows Installer.
• Navigate to Tomcat Package that was provided by us and copy over the moas folder to the newly installed Tomcat as a service directory root.
• Navigate to Tomcat As a Service Directory Root\conf and edit the server.xml file.
• Search for <Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true"> in the file.

• Add this line: <Context displayName="moas" docBase="../moas" path="/" reloadable="false" /> just below the line you searched for
• Now you can navigate to the windows services panel and start the Tomcat service.