4.8 KiB

Raw Blame History

MCIAS Installation and Usage Guide

MCIAS Installation and Usage Guide

MCIAS Installation and Usage Guide

Prerequisites

Before installing MCIAS, ensure you have the following prerequisites:

Go 1.23 or later
SQLite3
golangci-lint (for development)

Installation

Clone the Repository

git clone git.wntrmute.dev/kyle/mcias
cd mcias

Install Dependencies

go mod download

Initialize the Database

MCIAS uses SQLite for data storage. To initialize the database:

go run cmd/mcias/main.go init --db ./mcias.db

This command creates a new SQLite database file and initializes it with the schema defined in schema.sql.

Running the Server

Basic Usage

To start the MCIAS server with default settings:

go run cmd/mcias/main.go server --db ./mcias.db

By default, the server listens on port 8080.

Configuration Options

MCIAS supports the following command-line options for the server:

--db <path>: Path to the SQLite database file (default: mcias.db)
--addr <address>: Address to listen on (default: :8080)

Example with custom port:

go run cmd/mcias/main.go server --db ./mcias.db --addr :9000

Managing Users and Authentication

Adding a New User

To add a new user to the system:

go run cmd/mcias/main.go user add --username <username> --password <password>

Managing TOTP Authentication

To enable TOTP for a user:

go run cmd/mcias/main.go totp enable --username <username>

This will generate a TOTP secret for the user and display it. The user should save this secret in their authenticator app.

To add a TOTP token with QR code generation:

go run cmd/mcias/main.go totp add --username <username> --qr-output <path/to/qrcode.png>

To validate a TOTP code:

go run cmd/mcias/main.go totp validate --username <username> --code <totp_code>

Building from Source

To build the server binary:

cd cmd/mcias
go build -o mcias

Then run the binary:

./mcias server --db ./mcias.db

To build the client binary:

cd cmd/mcias-client
go build -o mcias-client

Development

Running Tests

To run all tests:

go test ./...

Linting

To run the linter:

golangci-lint run

Using the API

Authentication with Password

To authenticate a user with a password:

curl -X POST http://localhost:8080/v1/login/password \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1",
    "login": {
      "user": "username",
      "password": "password"
    }
  }'

Authentication with Token

To authenticate a user with a token:

curl -X POST http://localhost:8080/v1/login/token \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1",
    "login": {
      "user": "username",
      "token": "your_token"
    }
  }'

Authentication with TOTP

To authenticate a user with a password and TOTP code:

curl -X POST http://localhost:8080/v1/login/totp \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1",
    "login": {
      "user": "username",
      "password": "password",
      "totp": "123456"
    }
  }'

Retrieving Database Credentials

To retrieve database credentials:

curl -X GET "http://localhost:8080/v1/database/credentials?username=username" \
  -H "Authorization: Bearer your_token"

Troubleshooting

Common Issues

Database errors: Ensure the database file exists and has the correct permissions.

# Check permissions
ls -l mcias.db
# Fix permissions if needed
chmod 644 mcias.db

Port already in use: If the port is already in use, specify a different port with the -addr flag.
```
go run main.go -db ./mcias.db -addr :8081
```
Authentication failures: Ensure you're using the correct username and password/token.

Logging

MCIAS logs to stdout by default. To capture logs to a file:

go run main.go -db ./mcias.db > mcias.log 2>&1

Security Best Practices

Production Deployment:
- Use HTTPS in production
- Set up proper firewall rules
- Run the service with minimal privileges
Database Security:
- Regularly backup the database
- Restrict file permissions on the database file
- Consider encrypting the database file at rest
User Management:
- Implement strong password policies
- Regularly rotate tokens
- Monitor for suspicious authentication attempts

4.8 KiB Raw Blame History

MCIAS Installation and Usage Guide