MCIAS

• MCIAS
• Documentation
• Quick Start
• CLI Commands
  • Server CLI Commands
  • Server Command
  • Init Command
  • User Commands
  • Token Commands
  • TOTP Commands
  • Migrate Commands
• API Overview
  • Authentication Endpoints
    • /v1/login/password
    • /v1/login/token
    • /v1/credentials/database
  • Request Format
• Development
• Client Tool
  • Installation
  • Client CLI Commands
    • Login Commands
    • Database Commands
  • Configuration

MCIAS

MCIAS is the metacircular identity and access system, providing identity and authentication across metacircular projects.

It currently provides the following across metacircular services:

1. User password authentication.
2. User token authentication.
3. Database credential authentication.
4. TOTP (Time-based One-Time Password) authentication.

Future work should consider adding support for:

1. Policy management for fine-grained access control.

Documentation

Comprehensive documentation is available in the docs directory:

• Overview - Project overview, system architecture, database schema, and security considerations
• API Documentation - API endpoints, request/response formats, error handling, and authentication flow
• Installation and Usage Guide - Prerequisites, installation steps, running the server, and more

Quick Start

To get started with MCIAS:

1. Initialize the database:

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

2. Start the server:

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

3. The server will listen on port 8080 by default.

CLI Commands

MCIAS provides two command-line interfaces:

1. The server CLI (`mcias`) for managing the MCIAS server
2. The client CLI (`mcias-client`) for interacting with the MCIAS server

Server CLI Commands

Server Command

Start the MCIAS server:

go run cmd/mcias/main.go server [--db <path>] [--addr <address>]

Init Command

Initialize the database:

go run cmd/mcias/main.go init [--db <path>]

User Commands

Add a new user:

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

List all users:

go run cmd/mcias/main.go user list

Token Commands

Add a new token for a user:

go run cmd/mcias/main.go token add --username <username> [--duration <hours>]

List all tokens:

go run cmd/mcias/main.go token list

TOTP Commands

Enable TOTP for a user:

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

Add a TOTP token with QR code generation:

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

Validate a TOTP code:

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

Migrate Commands

Apply database migrations:

go run cmd/mcias/main.go migrate up [--migrations <dir>] [--steps <n>]

Revert database migrations:

go run cmd/mcias/main.go migrate down [--migrations <dir>] [--steps <n>]

Show current migration version:

go run cmd/mcias/main.go migrate version [--migrations <dir>]

API Overview

Authentication Endpoints

/v1/login/password

Password-based authentication endpoint.

/v1/login/token

Token-based authentication endpoint.

/v1/credentials/database

Database credential authentication endpoint (not yet fully implemented).

Request Format

The general datastructure used to log in should look like:

{
    "version": "v1",
    "login": {
        "user": "username",
        "password": "secret password",
        "token": "1234567890",
        "totp": "123456"
    }
}

Any fields that aren't used should be omitted. The version and login.user types are required, as well as the appropriate credential field.

Development

• Run tests: go test ./...
• Run linter: golangci-lint run
• Run specific linter: golangci-lint run --disable-all --enable=gosec

The project uses a strict golangci-lint configuration defined in .golangci.yml. This configuration includes a comprehensive set of linters focused on:

• Security best practices
• Code quality and maintainability
• Performance considerations
• Error handling correctness

See the Installation and Usage Guide for more details.

Client Tool

MCIAS includes a separate command-line client tool (`mcias-client`) that can be used to interact with the MCIAS server. The client tool provides access to all the APIs defined in the server.

Installation

To build and install the client tool:

cd cmd/mcias-client
go build -o mcias-client
# Optional: Move to a directory in your PATH
sudo mv mcias-client /usr/local/bin/

Client CLI Commands

Login Commands

Login with username and password:

mcias-client login password --username <username> --password <password> [--totp <code>]

Login with a token:

mcias-client login token --username <username> --token <token>

Database Commands

Get database credentials:

mcias-client database credentials --username <username> --token <token>

Or use a stored token from a previous login:

mcias-client database credentials --use-stored

Configuration

The client tool can be configured using command-line flags or a configuration file:

• `–server`: MCIAS server address (default: http://localhost:8080)
• `–token-file`: File to store authentication token (default: $HOME/.mcias-token)
• `–config`: Config file (default: $HOME/.mcias-client.yaml)

Example configuration file ($HOME/.mcias-client.yaml):

server: "http://mcias.example.com:8080"
token-file: "/path/to/token/file"