Loading...
This website provides documentation for administrators of 0th Root Secure Network — 0SNet. To know about the product, kindly visit our product website.
Getting Started
0th Root Secure Network — 0SNet works at the domain level and all subdomains of the chosen domain. For example, if you choose a domain
example.com then 0SNet will secure all subdomains of example.com ie.,
*.example.com. Ideally, a third level domain is chosen, such as
corp.example.com to secure
*.corp.example.com.
1. Network Firewall
It is important that whichever host you setup 0SNet on, only that host should have access to the protected servers. This will require establishing a network firewall on each of the servers.
2. Email Address
An administrator email address need to be specified at the time of configuration. This is the email address which will receive the password protected certificate. Only by using the certificate, can 0SNet be accessed. However, 0SNet can be reconfigured, if there were any mistakes made.
3. Operating System
The server hosting 0SNet should be capable of running Apache HTTP server (2.4.3+). Currently, RHEL 7 and its derivatives are supported, such as CentOS 7.
If you're on AWS or GCP or Azure, you can use our public
AMI or
Custom Image or
Shared Image Gallery
to launch a new instance, it comes with 0SNet pre-installed.
Installation
This section will help you through the process of installing 0SNet on your server. Please read Getting Started and have the domain information, administrator email, and the server details ready.
And, open ports 80 (HTTP) and 443 (HTTPS) on the server for 0SNet to work.
Manual |
AWS |
GCP |
AZURE |
1. Platform setup
Run the following command and set SELinux to disabled,
sudo sed -i "s/^SELINUX=.*$/SELINUX=disabled/" /etc/selinux/config
Restart the server,
sudo init 6
Once the server is up, run the following commands to start 0SNet server on boot,
sudo chmod +x /etc/rc.d/rc.local
sudo bash -c 'echo "0snet --start" >> /etc/rc.d/rc.local'
2. Pre-requisites
Install Apache HTTP server, the SSL module and the required tools, as follows,
sudo yum install httpd mod_ssl wget bind-utils cronie lsof
Ensure that default configuration of Apache HTTP server is not used,
sudo systemctl stop httpd.service
sudo systemctl disable httpd.service
sudo systemctl mask httpd.service
3. Installing 0SNet
To install the packages, 0snet and 0snet-uman, we need to directly use the rpm command instead of yum. This is because of the EULA that gets shown at the time of installation. Please run the following command to install 0SNet,
sudo rpm -Uvh https://www.0throot.com/download/x86_64/{0snet,0snet-uman}.el7.rpm
|
Public AMI
0SNet is available as a public amazon machine image (AMI) in N. Virginia, Mumbai and Singapore regions. If you require the AMI in any other region, we can make it available.1
In AWS console (see image below), choose the correct region,
- Open services and select EC2
- On the sidebar, select AMI under Images
- Select Public Images in the drop down to the left of search bar
- Search for keyword, 0snet
- Choose 0th Root Secure Network and click Launch 2
- Remember to open ports 80 and 443 when configuring Security Group
Once the instance is successfully created, add a wildcard DNS record for the chosen domain, such as *.corp.example.com, to its Elastic IP.
[1] You can also bear the minor costs and copy the AMI.
[2] To login to the new instance, SSH as ec2-user@Elastic-IP.
|
Custom Image
0SNet is available as a publicly shared custom image.
gcloud CLI can be used to create a new instance from this custom image. The uri of the image family is listed below,
https://www.googleapis.com/compute/v1/projects/id-0snet/global/images/family/stable-0snet
The following command1 creates a new instance from the custom image, with HTTP (80) and HTTPS (443) ports open,
gcloud compute instances create INSTANCENAME --image-family https://www.googleapis.com/compute/v1/projects/id-0snet/global/images/family/stable-0snet --tags http-server,https-server
On successful run of the above command, a new instance is created. Now, add a wildcard DNS record for the chosen domain, such as *.corp.example.com, to the displayed External IP.2
[1]
choose zone and machine type with options
--zone and --machine-type
[2]
remember to
make the external IP static
|
Shared Image Gallery
0SNet is available as an image in shared image gallery. To access the image in your Azure account, we will need to add Reader role to your email address under access control. Kindly send us your email address at support@0throot.com.
If the user is outside of your organization, they will get an email invitation to join the organization. The user needs to accept the invitation, then they will be able to see the gallery and all of the image definitions and versions in their list of resources.
Once you have accepted the invitation, you should see 0snet image in the list of resources,
- Open All services
- On the sidebar, select Compute
- Choose Image definitions
- Click on 0snet/stable image definition
- Under resource details, click Create VM
- Remember to open ports HTTP (80) and HTTPS (443)
|
0SNet is provided as per these terms of use and privacy policy .
If you face any problems, please feel free to contact us.
Configuration
If you have chosen a domain such as .corp.example.com. You should configure your nameserver (DNS) to resolve the wildcard entry *.corp.example.com to the IP address of 0SNet server.
When Google Sign-In or Microsoft Sign-In is enabled, 0SNet will require login through the corresponding user account. Hence, don't use group email address or a mailing list during configuration.
Setup (1/3)
Type the following command,
sudo 0snet --configure
This should bring up the following screen,
Fill out the form with your domain name, organization name, email ID and user ID. TLS certificate for the administrator will be sent to the specified email address. Choose your user ID carefully, because it will not be possible to modify this later.
IMPORTANT: Note down the password. In case you don't remember it, you can reconfigure 0SNet using,
sudo 0snet --configure
After the Setup Complete message, you should receive an email at the specified address, check your spam/bulk folder if necessary. The email should contain one attachment, sign.p12. It is your personal certificate encrypted using the password and it should be imported into your browser under personal certificates. If you are unsure, as to how to import the certificate, kindly follow the steps here.
Management Interface (2/3)
Once the certificate is imported, you will be able to access the management interface. A special subdomain 0snet is reserved for this purpose. For example, If you have configured your domain as .corp.example.com, you should open https://0snet.corp.example.com.
On successful connection, Browser will ask for a client certificate to be selected. On choosing the correct one, a login page for 0SNet will be shown. Enter the generated password, and change the password after successful login.
Hosts (3/3)
Host Manager should be used to add subdomains, along with IP address / Hostname of origin server, as shown in the image below,
After adding the subdomain, click on Validate Now to validate the domain. The new subdomain will be ready to use within 5 mins.
Certificates
0SNet sends an email to users containing their personal certificate file. In this section, the steps to import the certificate has been provided in detail,
Android / iOS / Windows / Mac
On most devices, simply opening the sign.p12 file (double-click or tap to open) is sufficient to import the certificate.
Preferences
On Linux / Firefox / Opera browser, Search for "certificates" in the browser settings or preferences, and you will likely find "Manage Certificates" or "View Certificates". On opening it, click the Import button under "Your Certificates" or "Personal Certificates" tab and choose the certificate file, sign.p12.
On Google Chrome, you can use the direct link chrome://settings/certificates.
When prompted for a password, type the generated password that has been provided by the administrator.
The certificate should be imported successfully.
To protect the imported certificates, it is recommended that you set a Master Password for the browser.
Role-based Access Controls
By default, all users have equal access to the subdomains, ie., *.corp.example.com. To differentiate users and grant access only to specific subdomain(s), ie., webapp.corp.example.com, access controls should be used. The link to access controls page can be found in user manager.
There are two distinct sections in access controls, ie., the Default and Groups sections.
Default
The default behavior of access controls is governed by this section. There are three components that work together, ie., mode, statements and exceptions, as shown in the image below,
The Update statements button will be disabled until mode or statements has been changed. On successful update, the access controls are immediately applied. Hence, it is recommended to make all the changes at once.
Mode
The default mode can be one of two values, Allow (or) Deny. In Allow mode, as the name suggests, all incoming requests are allowed after successful authentication, while in Deny mode, they are rejected as unauthorized.
Statements
To alter the default behavior, along with the default mode, statements can be used. The syntax of a statement is as follows,
<deny or allow> <subdomain> [</url> or </urlprefix>]
All statements in the example below are valid, they collectively define access for users,
allow myapp.corp.example.com
deny myapp.corp.example.com /this/path/*
deny webapp.corp.example.com /this/file.php
URL path prefix or an absolute path to file can be optionally specified, as shown in the example above. However, query string and anchor element cannot be matched.
Exceptions
To bypass default mode and statements, an exception can be added for specific users. An exception is an association of user to a specific mode. While an exception exists for the user, default mode and statements will not apply, and only the mode associated to the user will apply.
Groups
To specify access controls for a set of users, control groups can be used. Each group can have its own statements and users, as shown below,
Users can be part of multiple groups and control statements of all those groups will be used for authorization, along with default statements (if applicable). In case of conflicts, longer URL paths and deny statements take higher precedence.
NOTE: Admin user created at the time of 0SNet setup cannot be part of control groups.
To remove user from a control group, click on the user row and confirm. To quickly remove without any confirmation, hold CTRL key when clicking.
Version
Details of last update can be checked with,
sudo 0snet --ac
0SNet versions update to mode and/or statements, above command will output details of current version.
Google Sign-In
Instead of 0SNet password authentication, Google OAuth can be used through the Google Sign-In (GSI) feature. When GSI is used, the user is prompted with a Sign In button, as shown below, instead of the usual username and password,
The email address of the user should match the Google account used for login.
Configuration
Create a new client ID for 0SNet, in Google API Console, and specify the javascript origins. When 0SNet is configured for *.example.com, the javascript origins would be a.example.com, b.example.com and so on. Unlike 0SNet, wildcard is not supported, hence all internal applications and websites need to be added individually.
Enable GSI
The client ID can be set in 0SNet and GSI can be enabled using the command shown below,
sudo 0snet --gsi on [client-id]
To disable GSI at any point, the following command should be used,
sudo 0snet --gsi off
Do remember to restart 0SNet for changes to take effect,
sudo 0snet --stop && sudo 0snet --start
Process Changes
The user creation and certificate installation processes remain the same. Only at the time of login, the user is prompted with a Sign-In button instead of user name and password. Hence, with GSI, user doesn't need access to 0SNet password or username, expect at the time of certificate installation.
Demerits
When GSI is enabled, 0SNet Server requires access to public internet to function. It verifies the connection to external servers using the trusted root certificates available on the server, typically at /etc/pki/tls/certs/ca-bundle.crt. All CAs are treated equally, so it is important to keep the CA bundle upto date.
Microsoft Sign-In
Instead of password authentication method, 0SNet can be configured to use Microsoft OAuth 2.0 through the Microsoft Sign-In (MSI) feature. When MSI is enabled, users will be prompted with a Sign In button to login, as shown below,
The email address of the user should match the Microsoft account used for login.
Configuration
A client-id provided by Microsoft is needed to enable MSI in 0SNet. It can be found in Azure Active Directory.
An application need to be registered, as shown in the images below,
And, to support Sign-In across all sites configured under 0SNet, they need to be added under Redirect URIs for the application,
Enable MSI
The client-id can be set in 0SNet to enable MSI using the command shown below,
sudo 0snet --msi on [client-id]
To disable MSI at any point, the following command should be used,
sudo 0snet --msi off
Do remember to restart 0SNet for changes to take effect,
sudo 0snet --stop && sudo 0snet --start
Process Changes
The user creation and certificate installation processes remain exactly the same. Only at the time of login, users will be presented with a Microsoft Sign-In button. Hence, with MSI enabled, password for the user will need to be used only for certificate installation.
Demerits
Enabling MSI adds a dependency on Microsoft Login and Microsoft Graph API services. If any of them are down, users will not be able to login to 0SNet. This also essentially means, a public internet connection is required on the 0SNet server.
The connections to Microsoft services are verified using the trusted root certificates available on the server, typically at /etc/pki/tls/certs/ca-bundle.crt. All CAs are treated equally, so it is important to keep the CA bundle upto date.
License
0SNet incorporates a licensing system for easier distribution and sale of software. Every install of 0SNet comes with a license file which works for upto 5 users. You can review the license information using the following command,
$ sudo 0snet --license info
0throot license file
License Key : UzXE/CV82m6kysyrtYQfv6X13wX6tWdnR/IPeULoaroR
Product : 0th Root Secure Network
Domain : .corp.example.com
Organization : Example Company Ltd.
Date of Expiry : Dec 24, 2019 14:17 IST
Users : 5
Valid Upto : N/A
Contact us @ support@0throot.com for any queries.
License files are updated periodically (default: 1hr) through a cronjob. To update them manually, please run,
$ sudo 0snet --license sync
$
Pricing
To upgrade your license file to add more users, you can review our payment terms and purchase options listed below,
Total Users | Pricing (INR) | Pricing (USD) |
5 users | Free of charge | Free of charge |
50 users | Rs. 5000 per month | $100 per month |
each additional user | Rs. 100 per month | $2 per month |
When multiple servers are used to serve the same set of users, the following charges are applicable,
Server | Pricing (INR) | Pricing (USD) |
1st server | Rs. 0 per month | $0 per month |
each additional server | Rs. 3000 per month | $60 per month |
* All government taxes will be extra
IMPORTANT: Prices are tentative and subject to change.
Please feel free to contact us at support@0throot.com for further details.
Command Line Interface (CLI)
0snet --cli <action> <arguments>
actions:-
useradd, userreset, userdelete, userstatus, usergroup
arguments:-
--name "full name"
--email "email address"
--userid "user-id"
--group "group name"
--allow
--deny
--nocert
--enable
--disable
--add
--remove
--json
usage:-
useradd --name <> --email <> --userid <> [--group <>] [--allow | --deny]
userreset (--userid <> | --email <>)
userdelete (--userid <> | --email <>)
userstatus (--userid <> | --email <>) (--enable | --disable)
usergroup (--userid <> | --email <>) --group <> (--add | --remove)
DESCRIPTION
The --cli option of 0snet utility provides
a command line interface to manage users within 0th Root
Secure Network (0SNet). The utility can output in JSON
format for easier integrations, refer to OUTPUT section for
more details. And, to know more on possible integrations,
refer to INTEGRATION section.
useradd can be used to add new user, it requires
the --name, --email, --userid to be
specified. user-id should be a single word with one or more
of the following characters, a-z A-Z 0-9 - . _ :.
Optionally, the newly created user can be added to access
control groups by specifying the group name, with
--group argument. Multiple groups can be specified by
repeating --group. Additionally, --allow,
--deny can be used to set appropriate exception to
default access control statements for the new user. And,
--nocert to add the user without certificate.
By default, newly added users are enabled, and
they are not administrators. User manager should be
used to set the added user as an administrator, if
needed.
userreset will reset user certificate and
credentials. The command outputs the new password, and it
should be securely communicated to the user. When
--email is used, all users matching the email address
are reset.
userdelete can be used to delete user(s). All
users matching the email address are deleted when using
--email.
userstatus should be used when a user needs to be
disabled, or when a disabled user needs to be re-enabled. On
using the --email argument, all matching users are
updated.
usergroup will add or remove user(s) from the
specified list of groups. Multiple groups can be specified
by repeating the --group argument. In case of a
failure, the user(s) may be added or removed from some
groups and not all.
The actions userstatus and usergroup are
idempotent, and can be safely repeated, in case of
any error.
OUTPUT
In case of errors, the exit code of the command will be
non-zero. The output format for useradd will be,
<user-id> <password>
And, when --json argument is specified, the
output format changes to a JSON text, as follows,
{"status":{"code":0,"message":""},"output":{"<user-id>":"<password>"}}
In case of an error, the above JSON text will have
code set to non-zero value and message
will contain the description of the error.
For userreset, the output may contain multiple
user-ids and passwords, one per line, when --email
argument is used. The output JSON text can also have
multiple user-ids as keys with corresponding passwords as
values.
INTEGRATION
Scripts can be developed to process user information and
pass on to 0snet-cli to perform a specific action. This
could be a one-time task, such as for bulk addition of
users, or could be a cron job for periodically adding and
removing users.
A job management system could also be used, to securely
login to server and run 0snet-cli to perform a specific
action.
Exposing the actions of 0snet-cli as a service is NOT
RECOMMENDED, and HIGHLY DISCOURAGED.
EXAMPLES
In the examples below, the first line is the command
and the below lines are output of the command,
$ sudo 0snet --cli useradd --name "Example User" --email "user@example.com" --userid "example1"
example1 kfuKN16t
$ sudo 0snet --cli userstatus --userid "example1" --disable
updated user(s) successfully
$ sudo 0snet --cli userreset --userid "example1" --json
{"status":{"code":0,"message":""},"output":{"example1":"Ipt38AY8"}}
$ sudo 0snet --cli usergroup --userid "example1" --group "Employee" --add
updated users and groups successfully
$ sudo 0snet --cli userstatus --userid "example1" --enable --json
{"status":{"code":0,"message":"updated user(s) successfully"}}
$ sudo 0snet --cli userstatus --userid "example1"
example1 enabled
$ sudo 0snet --cli useradd --name "Example User (Mobile)" --email "user@example.com" --userid "example2" --group "Sales" --group "Employee" --deny --json
{"status":{"code":0,"message":""},"output":{"example2":"lbLgduIA"}}
$ sudo 0snet --cli userreset --email "user@example.com"
example2 RqaHy9zH
example1 Scrn3HJ3
$ sudo 0snet --cli userdelete --userid "example2"
deleted user(s) successfully
$ sudo 0snet --cli usergroup --userid "example1" --group "Employee" --remove
updated users and groups successfully
Let's Encrypt
0SNet provides tools for easier integration with Let's Encrypt TLS certificate. It internally uses Certbot client to obtain and manage Let's Encrypt issued TLS certificates.
NOTE: This feature is intended for setups where 0SNet server has a public IP and the default HTTP port 80 is available. In case of private setups, or where port 80 is used by a different program, the necessary domain validation cannot be done to get certificates.
Certbot
Package for Certbot client is available on various distributions. On CentOS/RHEL 7.x, one can run the following command to install the EPEL repository,
sudo yum install epel-release
and install the certbot package,
sudo yum install certbot
In case, the client couldn't be installed through the native package manager, the following command can be used to download and install Certbot client.
The install of Certbot will be local to 0SNet. However, additional dependent packages will get installed, and/or upgraded, during the process. And, in case of any errors, you can attempt an experimental install with the option --debug, but make sure you have taken the necessary backups before using it.
Hosts
0SNet is intended to secure all subdomains of the chosen domain, such as *.example.com. But, since, Let's Encrypt platform currently supports only multi-domain TLS certificates (upto 100 domains) over HTTP-01 challenge, and not wildcards, the list of subdomains used will be gathered by parsing the /etc/hosts file. This list of subdomains can be verified by running the command shown below,
It should be ensured that all required subdomains are part of the list, before fetching the TLS certificate. On adding a new subdomain, a new TLS certificate should be obtained (fetch) and enabled (on).
Certificate
Let's Encrypt certificates are domain validated and are issued immediately. To obtain a new certificate, the fetch command should be run as follows,
During the process, 0SNet server will be stopped and started, with the service being offline for a few minutes.
Enable/Disable
A newly issued certificate is not automatically used by 0SNet. To enable Let's Encrypt certificate, the following command should be run,
sudo 0snet --letsencrypt on
And, to switch back to the previous certificate, ie., stop using Let's Encrypt certificate, run the command below,
sudo 0snet --letsencrypt off
Renewal
0SNet checks the certificate for renewal daily and it gets automatically renewed. During the renewal process, which happen once in 2-3 months, the server may be offline for a few minutes.
The log messages are written to syslog, and is typically available at /var/log/messages, it should be checked for any errors during renewal.
Contact Us
0SNet is a product of 0th Root Software Research. For any questions (or) suggestions, please write to us at support@0throot.com
We are located at,
(Primary Address)
RMZ Latitude Commercial,
10th Floor,
Bellary Rd, Hebbal,
Bengaluru - 560 024. (INDIA)
No.24, Tatia Nagar Phase -3,
Nolambur, Maduravoyal PO,
Chennai - 600 095. (INDIA)
+91 44 2653 2984