How to Run CMD-Auth

1 An Overview of CMD-Auth

cmd-auth deploys a secure, thorough, efficient and highly scalable RESTful HTTP API for authentication, content and support.
cmd-auth can run on private networks and communicate with remote databases on private networks in order to greatly reduce the surface of attacks.
An upstream application should make requests to the API exposed by cmd-auth and consume its output.

The application is extremely resilient and secure and incorporates a multitude of innovative features designed to maximize security and performance.
The authentication is based on random cookies and Json Web Tokens.
There is no AI involved and there is no data collection.
Unlike other authentication systems you are the sole owner of the application data.

By no means this is a low-code or no-code application. It just wraps the backend, shields the database and provide an efficient and secure API which can be deployed, re-deployed and restored in seconds.
The performance is always optimum for the settings supplied. At the same time there are multiple built-in features which provide world-class resiliency.
Professionals which understand the efforts required in order to deploy and maintain applications at scale and want to do solid business in real-time with no fear of security flaws, will benefit the most from this application.

This applications designed to consume cmd-auth API can be done using any compatible programming language and framework available.
Own PHP framework CleanDeck can be used for ultra-fast development and deployment of applications.

cmd-auth is built for expansion and contraction with minimal effort and cost.
The following repeating scenario is fully handled by cmd-auth:

Additional resources may be required for specific use cases.

Another scenario for which cmd-auth is prepared is the one in which the developers of a web application have basic knowledge regarding the administration of the operating system (Linux), or simply have no time to perform OS administration.
The entire behavior of the application is controlled by settings which are delivered using instance User Data exposed by the cloud provider, or delivered through a custom URL. There is no need to access the operating system if a proper set of settings is supplied.

One of the most important aspects is that when using cmd-auth a developer does not need to access the database. Instead of making database calls, a developer should use the HTTP RESTful API exposed by cmd-auth. The application will handle database calls in an optimized fashion: connections are reused when possible, read-only connections are properly used when needed (if available), errors are handled gracefully a.m.o. It is still possible to use architectures where both the frontend application and cmd-auth are accessing the database.

cmd-auth uses significant resources. A machine running cmd-auth should have at least 2 threads and 1Gb RAM available. For logging and transfer of large database use root volumes with at least 10Gb. Use better specifications for increased performance. See /documentation for more details about the requirements of the application.

It is recommended to dedicate an entire machine to cmd-auth. If that is not possible, the next suggested solution is to keep cmd-auth as the main consumer of resources on the machine. In order to adjust the amount of resources used by the application, use the setting application -> systemd_slice_percentage.
The access to public networks should be restricted during development (suggested, only to the IPs doing development tasks), and completely forbidden in production.

Given below is the recommended combined set of skills required from a team in order to successfully deploy a basic web application which is using cmd-auth:

• Cloud operations: compute, security, databases, storage, VPC, domain, routing, frontend distributions
• HTTP
• REST
• APIs
• Basic Networking
• Linux administration (if direct intervention is required)
• SQL databases knowledge (if direct intervention is required)
• Any HTTP able backend programming language/framework
• Any frontend programming language

2 How to Get CMD-Auth

The application is usually delivered:

• By the cloud providers if agreements exist.
• Through a common Linux installation package usable in any environment (cloud, data-center etc.) - This option is for customers which have consistent experience with cmd-auth, frequently using a very high number of machines running cmd-auth and which are looking for maximum flexibility and the best price per unit. There is no limit on the number of instances a customer can use. Order from your account or Contact us.
• By other means soon

Custom versions of CMD-Auth can be ordered from your account. Alternatively you may Contact us. Requests for products delivered by us may be delayed depending on many factors which include personnel availability.

3 Prepare an AWS IAM Policy for CMD-Auth

cmd-auth requires a minimal set of permissions in order to be able to run all its features.
Using AWS IAM visual interface or AWS CLI, create a new policy.

Given below it's a starter AWS IAM JSON policy. Before using this policy, adjust as required in order to use all/some features of cmd-auth.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetObject",
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::my-logs-bucket",
                "arn:aws:s3:::my-uploads-bucket",
                "arn:aws:s3:::my-backups-bucket"
            ]
        }
    ]
}

Choose a relevant name and create the policy.

This policy should be used to create a fresh AWS IAM Role for cmd-auth as described in the next step.

4 Prepare an AWS IAM Role for CMD-Auth

A proper AWS IAM Role should be used when launching AWS EC2 instances running cmd-auth.

Start by selecting "AWS service" for Trusted entity type and "EC2" for Use case.

Use the AWS IAM policy created as specified in the previous section.

Use this role when starting a new AWS EC2 instance as described below.

5 Generate CMD-Auth Settings

It is very important to prepare a proper set of settings for your application normally before starting a machine which runs cmd-auth.
The following resources are available:

• CMD-Auth API and Documentation (including the full description of settings)
• CMD-Auth settings generator (check and adjust the settings generated before actually using them)

The settings which are not explicitly declared will take default values.

6 The Security of the Web Application

By default, the application deploys an HTTPS API using protocol HTTP/2.
It is recommended to stick with the default secure settings and adjust the stack accordingly.

The application/framework communicating with cmd-auth should use available means in order to skip certificate checks because by default the certificates used are self-signed and automatically generated every time the application (re)starts.
While most of the applications/frameworks have options to skip certificate checks, some of them do not implement them correctly in full and adjustment/overriding of defaults may be required. Consider also using specialized modules where available.
When required DevOps can use quick options such curl -k in order to skip certificate checks.

7 Launching an AWS EC2 Instance Running CMD-Auth

When launching AWS EC2 instances by any means available do not forget to:

• enter cmd-auth settings as AWS EC2 User Data adjusted as per your application needs (important)
• append the AWS IAM role adjusted as per your application needs (optional)

8 Monitoring CMD-Auth

Use the standard tools offered by the cloud provider in order to monitor machines and clusters which are running cmd-auth.

Standard AWS EC2 instance monitoring.

By default cmd-auth makes available the endpoint /machine/status. Use this endpoint to monitor the status of the operating system and the application. Please note that the availability of this endpoint is affected by settings. This endpoint should not be available on public networks in production.

The access to the operating system is unrestricted. Login and/or run your favorite tools for a detailed survey of the system and application.

The status of the systemd unit is updated every minute or when requested by endpoint /machine/status, and it can be retrieved programmatically:
sudo systemctl show --property=StatusText cmd-auth.service
# StatusText=Healthy { Requests=84086880 ; ThreadRestarts=0 }

9 Troubleshooting CMD-Auth

The standard procedures for troubleshooting Linux applications applies to cmd-auth as well:

• system logs - use standard tools to monitor/search for the output of the application i.e. journalctl -xf -u cmd-auth
• application logs - by default at /var/log/cmd-auth
• systemd unit information
  • sudo systemctl status -l cmd-auth.service
  • sudo systemctl show --property=StatusText cmd-auth.service
• others if necessary

Some versions of the application may be expired, or can be used only in certain conditions. In such situations the application will leave a notification which can be detected using the means above.
Please open a support case for every malfunction encountered while running the application.