mcias/client

MCIAS Client SDK

• Installation
• Usage
  • Creating a Client
  • Authentication
    • Password Authentication
    • Token Authentication
    • TOTP Verification
  • Retrieving Database Credentials
• Complete Example
• Error Handling
• Configuration Options

The MCIAS Client SDK provides a Go client for interacting with the Metacircular Identity and Access System (MCIAS). It allows applications to authenticate users and retrieve database credentials from an MCIAS server.

Installation

go get git.wntrmute.dev/kyle/mcias/client

Usage

Creating a Client

import "git.wntrmute.dev/kyle/mcias/client"

// Create a client with default settings (connects to http://localhost:8080)
c := client.NewClient()

// Create a client with custom settings
c := client.NewClient(
    client.WithBaseURL("https://mcias.example.com"),
    client.WithUsername("username"),
    client.WithToken("existing-token"),
)

Authentication

Password Authentication

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

tokenResp, err := c.LoginWithPassword(ctx, "username", "password")
if err != nil {
    log.Fatalf("Failed to login: %v", err)
}

fmt.Printf("Authenticated with token: %s\n", tokenResp.Token)
fmt.Printf("Token expires at: %s\n", time.Unix(tokenResp.Expires, 0).Format(time.RFC3339))

// Check if TOTP verification is required
if tokenResp.TOTPEnabled {
    fmt.Println("TOTP verification required")
    // See TOTP Verification section
}

Token Authentication

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

tokenResp, err := c.LoginWithToken(ctx, "username", "existing-token")
if err != nil {
    log.Fatalf("Failed to login with token: %v", err)
}

fmt.Printf("Authenticated with token: %s\n", tokenResp.Token)
fmt.Printf("Token expires at: %s\n", time.Unix(tokenResp.Expires, 0).Format(time.RFC3339))

TOTP Verification

If TOTP is enabled for a user, you'll need to verify a TOTP code after password authentication:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

totpResp, err := c.VerifyTOTP(ctx, "username", "123456") // Replace with actual TOTP code
if err != nil {
    log.Fatalf("Failed to verify TOTP: %v", err)
}

fmt.Printf("TOTP verified, token: %s\n", totpResp.Token)
fmt.Printf("Token expires at: %s\n", time.Unix(totpResp.Expires, 0).Format(time.RFC3339))

Retrieving Database Credentials

Once authenticated, you can retrieve database credentials:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

dbCreds, err := c.GetDatabaseCredentials(ctx)
if err != nil {
    log.Fatalf("Failed to get database credentials: %v", err)
}

fmt.Printf("Database Host: %s\n", dbCreds.Host)
fmt.Printf("Database Port: %d\n", dbCreds.Port)
fmt.Printf("Database Name: %s\n", dbCreds.Name)
fmt.Printf("Database User: %s\n", dbCreds.User)
fmt.Printf("Database Password: %s\n", dbCreds.Password)

Complete Example

Here's a complete example showing the authentication flow and database credential retrieval:

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "git.wntrmute.dev/kyle/mcias/client"
)

func main() {
    // Create a new client
    c := client.NewClient()

    // Create a context with timeout
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    // Authenticate with username and password
    tokenResp, err := c.LoginWithPassword(ctx, "username", "password")
    if err != nil {
        log.Fatalf("Failed to login: %v", err)
    }

    fmt.Printf("Authenticated with token: %s\n", tokenResp.Token)
    fmt.Printf("Token expires at: %s\n", time.Unix(tokenResp.Expires, 0).Format(time.RFC3339))

    // If TOTP is enabled, verify the TOTP code
    if tokenResp.TOTPEnabled {
        fmt.Println("TOTP is enabled, please enter your TOTP code")
        var totpCode string
        fmt.Scanln(&totpCode)

        totpResp, err := c.VerifyTOTP(ctx, "username", totpCode)
        if err != nil {
            log.Fatalf("Failed to verify TOTP: %v", err)
        }

        fmt.Printf("TOTP verified, new token: %s\n", totpResp.Token)
        fmt.Printf("Token expires at: %s\n", time.Unix(totpResp.Expires, 0).Format(time.RFC3339))
    }

    // Get database credentials
    dbCreds, err := c.GetDatabaseCredentials(ctx)
    if err != nil {
        log.Fatalf("Failed to get database credentials: %v", err)
    }

    fmt.Printf("Database Host: %s\n", dbCreds.Host)
    fmt.Printf("Database Port: %d\n", dbCreds.Port)
    fmt.Printf("Database Name: %s\n", dbCreds.Name)
    fmt.Printf("Database User: %s\n", dbCreds.User)
    fmt.Printf("Database Password: %s\n", dbCreds.Password)
}

Error Handling

All methods return errors that should be checked. The errors include detailed information about what went wrong, including API error messages when available.

Configuration Options

The client can be configured with the following options:

• WithBaseURL(baseURL string): Sets the base URL of the MCIAS server (default: "http://localhost:8080")
• WithHTTPClient(httpClient *http.Client): Sets a custom HTTP client (default: http.Client with 10s timeout)
• WithToken(token string): Sets an authentication token
• WithUsername(username string): Sets a username