mcias/clients/go

mcias-client (Go)

Go client library for the MCIAS identity and access management API.

Requirements

• Go 1.21+

Installation

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

Quick Start

import mciasgoclient "git.wntrmute.dev/kyle/mcias/clients/go"

// Connect to the MCIAS server.
client, err := mciasgoclient.New("https://auth.example.com", mciasgoclient.Options{})
if err != nil {
    log.Fatal(err)
}

// Authenticate.
token, expiresAt, err := client.Login("alice", "s3cret", "")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("token expires at %s\n", expiresAt)

// The token is stored in the client automatically.
// Call authenticated endpoints...
accounts, err := client.ListAccounts()

// Revoke the token when done.
if err := client.Logout(); err != nil {
    log.Fatal(err)
}

Custom CA Certificate

client, err := mciasgoclient.New("https://auth.example.com", mciasgoclient.Options{
    CACertPath: "/etc/mcias/ca.pem",
})

Error Handling

All methods return typed errors:

_, _, err := client.Login("alice", "wrongpass", "")
switch {
case errors.Is(err, new(mciasgoclient.MciasAuthError)):
    // 401 — wrong credentials or token invalid
case errors.Is(err, new(mciasgoclient.MciasForbiddenError)):
    // 403 — insufficient role
case errors.Is(err, new(mciasgoclient.MciasNotFoundError)):
    // 404 — resource not found
case errors.Is(err, new(mciasgoclient.MciasInputError)):
    // 400 — malformed request
case errors.Is(err, new(mciasgoclient.MciasConflictError)):
    // 409 — conflict (e.g. duplicate username)
case errors.Is(err, new(mciasgoclient.MciasServerError)):
    // 5xx — unexpected server error
}

All error types embed MciasError which carries StatusCode int and Message string.

Thread Safety

Client is safe for concurrent use from multiple goroutines. The internal token is protected by sync.RWMutex.

Running Tests

go test -race ./...