Kyle Isom
8f09e0e81a
- Update package declaration in client.go - Update error message strings to reference new package name - Update test package and imports to use new name - Update README.md documentation and examples with new package name - All tests pass
86 lines
1.9 KiB
Markdown
86 lines
1.9 KiB
Markdown
# mcias-client (Go)
|
|
|
|
Go client library for the [MCIAS](../../README.md) identity and access management API.
|
|
|
|
## Requirements
|
|
|
|
- Go 1.21+
|
|
|
|
## Installation
|
|
|
|
```sh
|
|
go get git.wntrmute.dev/kyle/mcias/clients/go
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```go
|
|
import "git.wntrmute.dev/kyle/mcias/clients/go/mcias"
|
|
|
|
// Connect to the MCIAS server.
|
|
client, err := mcias.New("https://auth.example.com", mcias.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
|
|
|
|
```go
|
|
client, err := mcias.New("https://auth.example.com", mcias.Options{
|
|
CACertPath: "/etc/mcias/ca.pem",
|
|
})
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
All methods return typed errors:
|
|
|
|
```go
|
|
_, _, err := client.Login("alice", "wrongpass", "")
|
|
switch {
|
|
case errors.Is(err, new(mcias.MciasAuthError)):
|
|
// 401 — wrong credentials or token invalid
|
|
case errors.Is(err, new(mcias.MciasForbiddenError)):
|
|
// 403 — insufficient role
|
|
case errors.Is(err, new(mcias.MciasNotFoundError)):
|
|
// 404 — resource not found
|
|
case errors.Is(err, new(mcias.MciasInputError)):
|
|
// 400 — malformed request
|
|
case errors.Is(err, new(mcias.MciasConflictError)):
|
|
// 409 — conflict (e.g. duplicate username)
|
|
case errors.Is(err, new(mcias.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
|
|
|
|
```sh
|
|
go test -race ./...
|
|
```
|