Skip to content

Commit 63cb07d

Browse files
jhubbardsfjhubbardsf
committed
feat: initial release (v1.0.0)
Automatic AWS SSO session refresh daemon for macOS. Features: - Proactively refreshes SSO sessions before they expire - Background daemon via launchd (runs every 10 minutes) - CLI commands: status, install, uninstall, logs, help - Configurable refresh threshold (default: 30 minutes) - Homebrew tap for easy installation
0 parents  commit 63cb07d

File tree

6 files changed

+872
-0
lines changed

6 files changed

+872
-0
lines changed

‎Formula/aws-sso-refresh.rb‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
class AwsSsoRefresh < Formula
2+
desc "Automatically refresh AWS SSO sessions before they expire"
3+
homepage "https://github.com/jhubbardsf/aws-sso-refresh"
4+
url "https://github.com/jhubbardsf/aws-sso-refresh/archive/refs/tags/v1.0.0.tar.gz"
5+
sha256 "" # Will be filled in after first release
6+
license "MIT"
7+
head "https://github.com/jhubbardsf/aws-sso-refresh.git", branch: "main"
8+
9+
depends_on "bash" => "4.0"
10+
depends_on "jq"
11+
depends_on "awscli"
12+
13+
def install
14+
bin.install "bin/aws-sso-refresh"
15+
end
16+
17+
def caveats
18+
<<~EOS
19+
To enable automatic background refresh:
20+
aws-sso-refresh install
21+
22+
To check your SSO session status:
23+
aws-sso-refresh status
24+
25+
The daemon will run every 10 minutes and refresh sessions
26+
that are within 30 minutes of expiring.
27+
EOS
28+
end
29+
30+
test do
31+
assert_match "aws-sso-refresh v", shell_output("#{bin}/aws-sso-refresh version")
32+
end
33+
end

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Josh Hubbard
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# aws-sso-refresh
2+
3+
Automatically refresh AWS SSO sessions before they expire, so you never hit "token expired" errors again.
4+
5+
## The Problem
6+
7+
When using AWS SSO (Identity Center), your session tokens expire after a few hours. This means you constantly have to run `aws sso login --profile xyz` when your tokens expire mid-task.
8+
9+
## The Solution
10+
11+
`aws-sso-refresh` runs as a background daemon and proactively refreshes your SSO sessions before they expire. It opens a browser window for re-authentication (which auto-approves if you're already logged in), so your tokens stay fresh.
12+
13+
## Installation
14+
15+
### Homebrew (recommended)
16+
17+
```bash
18+
brew install jhubbardsf/aws-sso-refresh/aws-sso-refresh
19+
```
20+
21+
### Manual / curl
22+
23+
```bash
24+
curl -fsSL https://raw.githubusercontent.com/jhubbardsf/aws-sso-refresh/main/install.sh | bash
25+
```
26+
27+
## Requirements
28+
29+
- **macOS** (uses launchd for background scheduling)
30+
- **bash 4.0+** (macOS ships with 3.2 - install with `brew install bash`)
31+
- **jq** (`brew install jq`)
32+
- **AWS CLI v2** (`brew install awscli`)
33+
34+
## Usage
35+
36+
```bash
37+
# Check your SSO session status
38+
aws-sso-refresh status
39+
40+
# Run a refresh check manually
41+
aws-sso-refresh
42+
43+
# Install the background daemon (runs every 10 minutes)
44+
aws-sso-refresh install
45+
46+
# View the refresh log
47+
aws-sso-refresh logs
48+
49+
# Remove the background daemon
50+
aws-sso-refresh uninstall
51+
52+
# Show help
53+
aws-sso-refresh help
54+
```
55+
56+
## How It Works
57+
58+
1. **Parses** your `~/.aws/config` to find all `[sso-session]` blocks
59+
2. **Checks** the token cache at `~/.aws/sso/cache/` for expiration times
60+
3. **Refreshes** sessions within 30 minutes of expiring via `aws sso login --sso-session <name>`
61+
4. **Opens a browser** for re-authentication (auto-approves if already logged in)
62+
63+
### Example Status Output
64+
65+
```
66+
AWS SSO Sessions:
67+
68+
✓ my-company-sso 5h 23m remaining
69+
✓ my-personal-sso 2h 10m remaining
70+
71+
Daemon: running (PID 1234)
72+
Interval: every 10 minutes
73+
Threshold: refresh when < 30m remaining
74+
```
75+
76+
## Configuration
77+
78+
### Refresh Threshold
79+
80+
By default, sessions are refreshed when they have less than 30 minutes remaining. Customize this with:
81+
82+
```bash
83+
export AWS_SSO_REFRESH_THRESHOLD=60 # Refresh when < 60 minutes remaining
84+
```
85+
86+
Add this to your `~/.zshrc` or `~/.bashrc` to persist.
87+
88+
### AWS Config
89+
90+
Your `~/.aws/config` should use the modern `sso-session` format:
91+
92+
```ini
93+
[sso-session my-sso]
94+
sso_start_url = https://my-company.awsapps.com/start
95+
sso_region = us-east-1
96+
sso_registration_scopes = sso:account:access
97+
98+
[profile dev]
99+
sso_session = my-sso
100+
sso_account_id = 123456789012
101+
sso_role_name = DeveloperAccess
102+
region = us-east-1
103+
104+
[profile prod]
105+
sso_session = my-sso
106+
sso_account_id = 123456789012
107+
sso_role_name = ReadOnlyAccess
108+
region = us-east-1
109+
```
110+
111+
With this setup, you only need to authenticate once per `sso-session`, not per profile!
112+
113+
## Files
114+
115+
| Path | Purpose |
116+
|------|---------|
117+
| `~/.aws/config` | Your AWS configuration with SSO sessions |
118+
| `~/.aws/sso/cache/` | AWS SSO token cache |
119+
| `~/.local/share/aws-sso-refresh/refresh.log` | Daemon log file |
120+
| `~/Library/LaunchAgents/com.aws.sso-refresh.plist` | macOS LaunchAgent |
121+
122+
## Troubleshooting
123+
124+
### "This script requires bash 4.0 or later"
125+
126+
macOS ships with bash 3.2 (from 2007!) due to licensing. Install modern bash:
127+
128+
```bash
129+
brew install bash
130+
```
131+
132+
### Sessions not refreshing
133+
134+
1. Check the daemon is running: `aws-sso-refresh status`
135+
2. Check the logs: `aws-sso-refresh logs`
136+
3. Run manually to test: `aws-sso-refresh`
137+
138+
### Browser doesn't auto-approve
139+
140+
Your Identity Center session may have expired. You'll need to manually approve in the browser once, then subsequent refreshes should be automatic.
141+
142+
## License
143+
144+
MIT - See [LICENSE](LICENSE) for details.
145+
146+
## Contributing
147+
148+
Contributions welcome! Please open an issue or PR on GitHub.

0 commit comments

Comments
 (0)