{"id":30624455,"url":"https://github.com/adonmo/aws-sso-lib-go","last_synced_at":"2025-08-30T17:15:53.708Z","repository":{"id":307350140,"uuid":"1029232052","full_name":"adonmo/aws-sso-lib-go","owner":"adonmo","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-30T18:47:14.000Z","size":40,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-30T21:01:50.257Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adonmo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-30T18:08:17.000Z","updated_at":"2025-07-30T18:47:01.000Z","dependencies_parsed_at":"2025-07-30T21:01:56.898Z","dependency_job_id":"6f01e2b5-b563-4162-bbf3-77c6852020f5","html_url":"https://github.com/adonmo/aws-sso-lib-go","commit_stats":null,"previous_names":["adonmo/aws-sso-lib-go"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/adonmo/aws-sso-lib-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonmo%2Faws-sso-lib-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonmo%2Faws-sso-lib-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonmo%2Faws-sso-lib-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonmo%2Faws-sso-lib-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adonmo","download_url":"https://codeload.github.com/adonmo/aws-sso-lib-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonmo%2Faws-sso-lib-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272878330,"owners_count":25008339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-30T17:15:49.177Z","updated_at":"2025-08-30T17:15:53.703Z","avatar_url":"https://github.com/adonmo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# aws-sso-lib-go\n\nA Go library and CLI tool for AWS IAM Identity Center (formerly AWS SSO) that makes it easier to work with multiple AWS accounts and roles.\n\nThis project is inspired by the Python [aws-sso-util](https://github.com/benkehoe/aws-sso-util) project and provides similar functionality for Go developers.\n\n## Features\n\n- **Library (`awsssolib`)**: Core functionality for programmatic interaction with AWS SSO\n  - Get AWS credentials for specific accounts and roles\n  - Interactive browser-based SSO login\n  - List available accounts and roles\n  - Credential caching and management\n  - Support for multiple SSO instances\n  - **🎉 NEW**: Comprehensive structured logging with `log/slog`\n\n- **CLI Tool (`aws-sso-util`)**: Command-line utilities for AWS SSO operations\n  - Configure AWS profiles in `~/.aws/config`\n  - Login/logout from SSO\n  - List available roles\n  - Run commands with specific account/role credentials\n  - Open AWS Console in browser\n  - Admin utilities for SSO management\n  - **🎉 NEW**: `--verbose` flag for detailed debug logging\n\n## Installation\n\n### CLI Tool\n\n#### Go Install (Recommended)\n```bash\ngo install github.com/adonmo/aws-sso-lib-go/cmd/aws-sso-util@latest\n```\n\n#### Download Pre-built Binaries\nDownload the latest release from [GitHub Releases](https://github.com/adonmo/aws-sso-lib-go/releases):\n\n```bash\n# Linux (x64)\ncurl -L https://github.com/adonmo/aws-sso-lib-go/releases/latest/download/aws-sso-util-linux-amd64.tar.gz | tar xz\n\n# macOS (Intel)\ncurl -L https://github.com/adonmo/aws-sso-lib-go/releases/latest/download/aws-sso-util-darwin-amd64.tar.gz | tar xz\n\n# macOS (Apple Silicon)\ncurl -L https://github.com/adonmo/aws-sso-lib-go/releases/latest/download/aws-sso-util-darwin-arm64.tar.gz | tar xz\n\n# Windows\n# Download aws-sso-util-windows-amd64.zip from releases page\n```\n\n#### Build from Source\n```bash\ngit clone https://github.com/adonmo/aws-sso-lib-go.git\ncd aws-sso-lib-go\nmake build\n# Binary will be in ./dist/aws-sso-util\n```\n\n### Library\n\n```bash\ngo get github.com/adonmo/aws-sso-lib-go\n```\n\n## Library Usage\n\n### Get a session for a specific account and role\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n    \n    \"github.com/adonmo/aws-sso-lib-go/awsssolib\"\n    \"github.com/aws/aws-sdk-go-v2/service/s3\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    \n    // Optional: Configure structured logging\n    config := awsssolib.DefaultConfig() // INFO-level logging\n    \n    // Get AWS SDK config for a specific account and role\n    cfg, err := awsssolib.GetAWSConfig(ctx, awsssolib.GetAWSConfigInput{\n        StartURL:   \"https://my-sso.awsapps.com/start\",\n        SSORegion:  \"us-east-1\",\n        AccountID:  \"123456789012\",\n        RoleName:   \"MyRole\",\n        Region:     \"us-west-2\",\n        Login:      true, // Interactively log in if needed\n        Config:     config, // Enable structured logging\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    \n    // Use the config with any AWS SDK v2 client\n    client := s3.NewFromConfig(cfg)\n    \n    // ... use the client\n}\n```\n\n### Login to SSO\n\n```go\n// Basic login\ntoken, err := awsssolib.Login(ctx, awsssolib.LoginInput{\n    StartURL:  \"https://my-sso.awsapps.com/start\",\n    SSORegion: \"us-east-1\",\n})\nif err != nil {\n    log.Fatal(err)\n}\nfmt.Printf(\"Logged in successfully, token expires at: %s\\n\", token.ExpiresAt)\n\n// Login with structured logging\nconfig := awsssolib.DefaultConfig()\ntoken, err := awsssolib.Login(ctx, awsssolib.LoginInput{\n    StartURL:  \"https://my-sso.awsapps.com/start\",\n    SSORegion: \"us-east-1\",\n    Config:    config, // Enable logging\n})\n```\n\n### List available accounts and roles\n\n```go\n// List all available accounts\naccounts, err := awsssolib.ListAvailableAccounts(ctx, awsssolib.ListAccountsInput{\n    StartURL:  \"https://my-sso.awsapps.com/start\",\n    SSORegion: \"us-east-1\",\n    Login:     true,\n})\nif err != nil {\n    log.Fatal(err)\n}\n\nfor _, account := range accounts {\n    fmt.Printf(\"Account: %s (%s)\\n\", account.AccountName, account.AccountID)\n}\n\n// List all available roles\nroles, err := awsssolib.ListAvailableRoles(ctx, awsssolib.ListRolesInput{\n    StartURL:  \"https://my-sso.awsapps.com/start\",\n    SSORegion: \"us-east-1\",\n    Login:     true,\n})\nif err != nil {\n    log.Fatal(err)\n}\n\nfor _, role := range roles {\n    fmt.Printf(\"Role: %s in account %s (%s)\\n\", \n        role.RoleName, role.AccountName, role.AccountID)\n}\n```\n\n### Structured Logging\n\nThe library includes comprehensive structured logging support using Go's standard `log/slog` package:\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log/slog\"\n    \"os\"\n    \"github.com/adonmo/aws-sso-lib-go/awsssolib\"\n)\n\nfunc main() {\n    // Create a JSON logger with DEBUG level\n    jsonLogger := slog.New(slog.NewJSONHandler(os.Stderr, \u0026slog.HandlerOptions{\n        Level: slog.LevelDebug,\n    }))\n    \n    // Create configuration with custom logger\n    config := awsssolib.NewConfig(jsonLogger, slog.LevelDebug)\n    \n    // All operations will now produce structured logs\n    accounts, err := awsssolib.ListAvailableAccounts(context.Background(), awsssolib.ListAccountsInput{\n        StartURL:  \"https://my-sso.awsapps.com/start\",\n        SSORegion: \"us-east-1\",\n        Config:    config, // Enable detailed logging\n    })\n    \n    // Logs will include structured data like:\n    // {\"time\":\"2024-12-19T10:30:45Z\",\"level\":\"INFO\",\"msg\":\"Starting SSO login\",\"start_url\":\"https://...\"}\n    // {\"time\":\"2024-12-19T10:30:46Z\",\"level\":\"DEBUG\",\"msg\":\"Checking for cached SSO token\"}\n    // {\"time\":\"2024-12-19T10:30:47Z\",\"level\":\"INFO\",\"msg\":\"Using cached SSO token\",\"expires_at\":\"2024-12-19T18:30:45Z\"}\n}\n```\n\n**Key Features:**\n- **Security-aware**: No sensitive data (tokens, credentials) ever logged\n- **Production-ready**: Configurable log levels and output formats\n- **Zero overhead**: No performance impact when logging is disabled\n- **Integration-friendly**: Works with any `slog.Handler` implementation\n\nFor complete documentation, see [STRUCTURED_LOGGING.md](./STRUCTURED_LOGGING.md).\n\n## CLI Usage\n\n### Configure AWS profiles\n\n```bash\n# Set default SSO configuration\nexport AWS_DEFAULT_SSO_START_URL=https://my-sso.awsapps.com/start\nexport AWS_DEFAULT_SSO_REGION=us-east-1\n\n# Configure a single profile interactively\naws-sso-util configure profile my-profile\n\n# Populate all available roles as profiles\naws-sso-util configure populate --regions us-east-1,us-west-2\n```\n\n### Login and logout\n\n```bash\n# Login to SSO (will open browser)\naws-sso-util login\n\n# Login with verbose debug logging\naws-sso-util login --verbose\n\n# Login with specific start URL\naws-sso-util login --start-url https://my-sso.awsapps.com/start --sso-region us-east-1\n\n# Logout\naws-sso-util logout\n```\n\n### List available roles\n\n```bash\n# List all available roles\naws-sso-util roles\n\n# Filter by account\naws-sso-util roles --account 123456789012\n```\n\n### Run commands with specific credentials\n\n```bash\n# Run a command as a specific account/role\naws-sso-util run-as --account 123456789012 --role MyRole -- aws s3 ls\n\n# Run with a specific region\naws-sso-util run-as --account 123456789012 --role MyRole --region us-west-2 -- aws ec2 describe-instances\n```\n\n### Open AWS Console\n\n```bash\n# Open console for a specific account/role\naws-sso-util console --account 123456789012 --role MyRole\n\n# Open a specific service\naws-sso-util console --account 123456789012 --role MyRole --service ec2\n```\n\n## Configuration\n\nThe tool respects the following environment variables:\n\n- `AWS_DEFAULT_SSO_START_URL`: Default SSO start URL\n- `AWS_DEFAULT_SSO_REGION`: Default SSO region\n- `AWS_SSO_CACHE_DIR`: Directory for SSO token cache (default: `~/.aws/sso/cache`)\n- `AWS_CLI_CACHE_DIR`: Directory for CLI credential cache (default: `~/.aws/cli/cache`)\n\n## Development\n\n### Prerequisites\n\n- Go 1.21 or later\n- Make (optional, for using Makefile)\n\n### Building\n\n```bash\n# Build the library\ngo build ./...\n\n# Build the CLI\ngo build -o aws-sso-util ./cmd/aws-sso-util\n\n# Run tests\ngo test ./...\n\n# Run with race detector\ngo test -race ./...\n```\n\n### Project Structure\n\n```\naws-sso-lib-go/\n├── awsssolib/          # Core library package\n│   ├── sso.go          # SSO authentication and token management\n│   ├── config.go       # Configuration and profile management\n│   ├── credentials.go  # Credential fetching and caching\n│   ├── browser.go      # Browser interaction for login\n│   └── cache.go        # Token and credential caching\n├── cmd/\n│   └── aws-sso-util/   # CLI application\n│       ├── main.go\n│       └── commands/   # CLI command implementations\n├── examples/           # Example usage\n└── docs/              # Additional documentation\n```\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nThis project is inspired by and based on the design of [aws-sso-util](https://github.com/benkehoe/aws-sso-util) by Ben Kehoe.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadonmo%2Faws-sso-lib-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadonmo%2Faws-sso-lib-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadonmo%2Faws-sso-lib-go/lists"}