123 lines
3.0 KiB
Org Mode
123 lines
3.0 KiB
Org Mode
#+title: MCIAS
|
|
#+created: <2025-05-09 Fri 13:42>
|
|
|
|
* 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.
|
|
|
|
Future work should consider adding support for:
|
|
1. TOTP (Time-based One-Time Password)
|
|
2. Policy management for fine-grained access control.
|
|
|
|
* Documentation
|
|
|
|
Comprehensive documentation is available in the [[file:docs/][docs]] directory:
|
|
|
|
- [[file:docs/overview.org][Overview]] - Project overview, system architecture, database schema, and security considerations
|
|
- [[file:docs/api.org][API Documentation]] - API endpoints, request/response formats, error handling, and authentication flow
|
|
- [[file:docs/installation.org][Installation and Usage Guide]] - Prerequisites, installation steps, running the server, and more
|
|
|
|
* Quick Start
|
|
|
|
To get started with MCIAS:
|
|
|
|
1. Initialize the database:
|
|
#+begin_src bash
|
|
go run main.go init --db ./mcias.db
|
|
#+end_src
|
|
|
|
2. Start the server:
|
|
#+begin_src bash
|
|
go run main.go server --db ./mcias.db
|
|
#+end_src
|
|
|
|
3. The server will listen on port 8080 by default.
|
|
|
|
* CLI Commands
|
|
|
|
MCIAS provides a command-line interface with the following commands:
|
|
|
|
** Server Command
|
|
|
|
Start the MCIAS server:
|
|
#+begin_src bash
|
|
go run main.go server [--db <path>] [--addr <address>]
|
|
#+end_src
|
|
|
|
** Init Command
|
|
|
|
Initialize the database:
|
|
#+begin_src bash
|
|
go run main.go init [--db <path>]
|
|
#+end_src
|
|
|
|
** User Commands
|
|
|
|
Add a new user:
|
|
#+begin_src bash
|
|
go run main.go user add --username <username> --password <password>
|
|
#+end_src
|
|
|
|
List all users:
|
|
#+begin_src bash
|
|
go run main.go user list
|
|
#+end_src
|
|
|
|
** Token Commands
|
|
|
|
Add a new token for a user:
|
|
#+begin_src bash
|
|
go run main.go token add --username <username> [--duration <hours>]
|
|
#+end_src
|
|
|
|
List all tokens:
|
|
#+begin_src bash
|
|
go run main.go token list
|
|
#+end_src
|
|
|
|
* 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:
|
|
|
|
#+begin_src json
|
|
{
|
|
"version": "v1",
|
|
"login": {
|
|
"user": "username",
|
|
"password": "secret password",
|
|
"token": "1234567890",
|
|
"totp": "123456"
|
|
}
|
|
}
|
|
#+end_src
|
|
|
|
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=
|
|
|
|
See the [[file:docs/installation.org][Installation and Usage Guide]] for more details.
|