Steps to Setup On-Premise IDP

The miniOrange On-Premise Identity Provider (IdP) securely manages and verifies user identities within your local environment for SSO and IAM. This quick-start guide walks you through deploying an instance of miniOrange IAM (v5.0.0) on Linux. Designed for rapid evaluation and testing, this setup uses a pre-packaged Tomcat server.

For architecture, moctl utility commands, and licensing details, use the links in Further References.

System Requirements

Ensure your server meets these basic specs before starting. The miniOrange installer is self-contained and will automatically prompt you to install Java 17, Redis, RabbitMQ, and a default database(PostgreSQL) if they are not already present on your system.

OS	Any operating system (Linux preferred) with support upto Java 17 (OpenJDK)
Hardware	4 Core CPU \| 16 GB RAM \| 32 GB Storage
JAVA Environment	JAVA_17
Server Access Policies	Port 80 - HTTP Port 1812 & 1813 - Radius UDP (optional) Port 22 - SSH (Linux Server) - For login
Software Dependencies	Database: PostgreSQL, MSSQL, MySQL, or Oracle. Find the list of all supported versions here. Redis: port 6379 RabbitMQ: port 5672

RADIUS ports 1812 & 1813 are optional, Open them only if you intend to use RADIUS-based Authentication.

If you prefer not to use the bundled internal components, you can connect the IAM to external servers hosting Redis, RabbitMQ, or a custom database (PostgreSQL, MSSQL, MySQL, or Oracle). For compatible external database versions, see the Full Database Support List.

Install On-Premise Server

1: Download the Installer

Option 1: Online Installation (Recommended)
Download the standard installer package directly to your server: Download Installer v5.0.0
Option 2: Offline Installation (Air-Gapped Environments)
For servers without internet access or in air-gapped environments, an offline installer is available upon request. Contact us with your OS name and version, and we will provide the appropriate installation package.

2: Run the Installer

Extract the package and execute the installation script by running the following commands in your terminal:

unzip mo-installer-5.0.0.zip
cd mo-installer-5.0.0
chmod +x *.sh
sudo sh mo-installer.sh

3: Respond to Interactive Prompts

During execution, the installer will detect missing dependencies and prompt you to install RabbitMQ and a PostgreSQL database locally.

For evaluation/POC setups: Type YES to install both locally. This is the fastest way to get a fully functioning instance up and running.
For external setups: Type NO if you prefer to host Redis, RabbitMQ or your database on a separate server.

4: External Configuration (Optional)

If you responded NO to the bundled PostgreSQL,Redis,RabbitMQ installation, you can download and use any external service of your choice.

Service	Ubuntu/Debian	CentOS/RedHat
PostgreSQL	Ubuntu/Debian	CentOS/RedHat
MySQL	Ubuntu/Debian	CentOS/RedHat
RabbitMQ	Ubuntu/Debian	CentOS/RedHat
Redis	Ubuntu/Debian	CentOS/RedHat

The only requirement: You must manually create a fresh, empty database (schema) inside your database server before continuing with the miniOrange setup wizard.

Example for PostgreSQL:

# Access your database CLI
sudo -u postgres psql

# Create a fresh, empty database
CREATE DATABASE <databasename>;

Note: (Replace <databasename> with your preferred identifier. You will enter this name into the miniOrange setup screen later).

Setup and configure the Identity Provider (IdP)

1. Start the IAM Services

Launch the miniOrange IAM platform by running the service utility. This command initializes all underlying required services automatically.

moctl service start

Note: The command line will display initialization progress. It may take a couple of minutes for all background services to fully boot up.

2. Access the Configuration Wizard

Open your web browser and navigate to: https://<YOUR_SERVER_IP_OR_DNS> e.g., ([https://192.168.1.2], [http://localhost:8080]).
Bypass SSL Warning: Because the initial setup uses a temporary self-signed certificate, your browser will show a security warning. Click Advanced and proceed to the address.

3. Complete the Setup Wizard

Follow the 3-step on-screen prompts to complete the deployment:

Service Infrastructure: Provide the connection details for your Database, RabbitMQ, and Redis setups, then click Next. (If you run into issues here, please check the FAQ or contact support).
Create Admin Account: Enter a valid administrator Email Address and secure Password. This will be your root credential for the admin dashboard. Click Next.
Use-Case Selection: Choose a predefined authentication template that matches your organizational goals, or click Skip to head straight to the dashboard.

4. Verify Service Health

Once you land on the dashboard, verify that all auxiliary microservices are functioning correctly using one of the following methods:

Method A: Via Command Line (Recommended)

Run the status check utility to ensure key services like apps, idps, and directory are listed as UP:

moctl service status

Method B: Via Web Browser

Navigate to the internal service registry engine at http://<YOUR_SERVER_IP_OR_DNS>:8070 or http://localhost:8070 to verify all components have registered successfully. You should see entries for core components such as APPS, CONFIGSERVER, DIRECTORY, IDPS, LICENSING, and other deployed services listed in the registry.

If any services are unavailable or not registered, restart the platform services and verify their status again:

moctl service restart

5. Import SSL Certificate into JDK Truststore (Required for Workflows)

Workflows require secure communication over HTTPS.

To ensure the Workflow service trusts your domain certificate, you must import the certificate into the JDK’s cacerts truststore.
Default keystore password: changeit
[Note: The location of the cacerts file depends on your JDK installation.]

Use the below command to import your domain certificate into the JDK truststore:

sudo keytool -import \
  -alias miniorange-wildcard \
  -file /home/abhishek/Downloads/certificates/domain.crt \
  -keystore /usr/lib/jvm/java-8-openjdk/jre/lib/security/cacerts \
  -storepass changeit

If your JDK is installed at a different path, update the -keystore location accordingly.

Common alternate paths:

/usr/lib/jvm/java-17-openjdk-amd64/jre/lib/security/cacerts

/usr/lib/jvm/java-17-openjdk/lib/security/cacerts

/opt/jdk/jre/lib/security/cacerts

6. Register Workflow Module with Scheduler

To enable workflow execution, you must register the Workflow module with the Scheduler service. Follow the steps based on your operating system.

Go to the installed miniOrange directory.

Navigate to:

/services/linux/scheduler-mq-register.sh

Example navigation:
```
cd /opt/mo-idp-server/services/linux/
```
Run the registration script:
```
sudo ./scheduler-mq-register.sh
```

How to Apply a SSL Certificate for Nginx:

Supported Certificate Formats for Nginx:
- PEM format (recommended: .crt, .cer, .pem)
- Private key must be in PEM format (.key).
- Nginx does not support certificates in DER or PFX formats directly. Use OpenSSL to convert them before using.

Generate SSL Certificate (optional if you don't have a CA-Signed Certificate)

1. Requirements

Ensure you have OpenSSL installed on your system:

sudo apt install openssl

2. Generate a Self-Signed Certificate

Run this command in your terminal:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout nginx-selfsigned.key -out nginx-selfsigned.crt \
  -subj "/C=US/ST=State/L=City/O=Company/OU=Org/CN=example.com"

Command Breakdown:

Flag	Description
-x509	Generates a self-signed certificate
-nodes	No password for the private key
-days 365	Certificate valid for 1 year
-keyout	Path to save the private key
-out	Path to save the certificate
-subj	Set certificate details without prompts

-subj Format:

/C=US/ST=State/L=City/O=Company/OU=Org/CN=example.com

Field	Meaning	Example
C	Country code (2 letters)	US, IN, DE
ST	State/Province	California, Karnataka
L	City	San Francisco, Bangalore
O	Organization	Acme Corp
OU	Department	IT, Engineering
CN	Domain name	example.com

Apply SSL Certificate in Nginx

1. Locate nginx.conf

Run:
```
/etc/nginx/nginx.conf
```

2. Edit the Server Block

server {
  listen 443 ssl;
  server_name example.com;  # Replace with your domain

  ssl_certificate     /path/to/nginx-selfsigned.crt;
  ssl_certificate_key /path/to/nginx-selfsigned.key;

  location / {
    # Your application settings
  }
}

3. Restart Nginx

Run:

sudo nginx -t # Test configuration
  sudo systemctl restart nginx

Note: Self-signed certificates will show a browser warning because they are not issued by a trusted Certificate Authority (CA). Use only for local development or internal testing.

For Self Signed Certificate
For Certificates from Trusted CAs

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 in this step.Then change the location in command prompt or terminal to Desktop or any other location of your choice.
Enter your convenient password and remember it.(If the password you entered didn’t work then keep the password as “changeit” ).

2. Generate SSL Certificate

After Pressing the Return key it will prompt for a password for <onpremssoidp>. 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.

3. Configure Tomcat with above-generated Keystore

1. Open Tomcat Configuration:

Navigate to the conf directory within the miniOrange installation folder.
Open the server.xml file in a text editor.

2. Edit server.xml:

Locate the line <Service name=”Catalina”>.

Immediately after this line, insert the following 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>"/>

Replace <JKS Keystore Path> with your keystore file path and <Password while keystore generation> with your keystore password.

Note: Make sure the .jks file has appropriate permissions/run command prompt as Administrator.

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="443" 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 <GoDaddyCertificate>.crt -inkey <PrivateKey>.key \
  -out <PublicPrivateKeyPair>.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”.
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 don't work follow the link given below
Click here to follow the steps if you have any other CA certificates.

Configure Log Rotation

The miniOrange core components generate continuous runtime logs. To prevent your server storage from completely filling up and causing service crashes over time, you must configure log rotation.

Please review and implement the configuration steps detailed in our standalone Log Rotation Configuration Guide immediately following your initial setup.

Upgrade On-Premise IDP

Note: During the miniOrange upgrade to a Java 17 runtime, any custom certificates present in the Java 8 cacerts truststore must be manually exported and imported into the Java 17 cacerts truststore to maintain trusted SSL connections with external systems.

Prerequisites:

Login to your admin account and go to Settings>>Product Settings. Copy your Server Base URL.
Take a backup of the miniorange db in your db instance.
Take a backup of the following files in the server.

mo-idp-server-*/moas/WEB-INF/classes/db.properties
mo-idp-server-*/moas/WEB-INF/classes/license

Go to mo-idp-server-*/bin and Shut down the running tomcat instance. (you can use sh shutdown.sh)

Steps to upgrade:

Download the latest version to your linux server and unzip it.
You will find moas folder inside the uncompressed folder. Replace the mo-idp-server-3.3.*/moas with the new moas folder
Replace the backups of db.properties and license file on the same path as mentioned above.
Go to mo-idp-server-*/bin and Shut down the running tomcat instance. (you can use sh shutdown.sh)
Restart the tomcat instance using sh startup.sh
Open a browser and go to < Your-Server-Base-URL >/initialize

Uninstall On-Premise IDP

To completely remove miniOrange IAM from your server, navigate to your installation directory and run:

# 1. Stop all active services
moctl service stop

# 2. Run the uninstaller script
sudo sh uninstall.sh

Frequently Asked Questions

Error Handling for Keystore Issues

If you encounter the error:"keytool error: java.lang.Exception: Key pair not generated, alias <onpremssoidp> already exists"

This indicates that the keystore file already exists. To resolve this, follow these steps:

Delete the existing keystore file located from path <Path to JAVA_HOME/bin> file named as "onpremssoidp.jks"

Rerun the key generation command

keytool -genkey -alias onpremssoidp -keyalg RSA -keystore onpremssoidp.jks

and fill in the details.

Further References

Architecture & Operations:

On-Premise Architecture Matrix: Deep dive into production & distributed layouts.
Identity Platform Admin Handbook: Complete day-to-day administration guide.
Log Rotation Configuration: Prevent disk space issues by setting up log rotation.

Service Management:

moctl: Service Management Guide: Full list of CLI commands and flags.

Licensing:

How to Generate your On-Premise License: Step-by-step License generation.
How to Update an Existing License: Renewing or upgrading your current license.

Contents