71 lines
3.6 KiB
Markdown
71 lines
3.6 KiB
Markdown
---
|
|
name: garmin-auth
|
|
description: Manage Garmin Connect authentication, proactive OAuth token keepalives, and interactive 2-turn MFA login over Telegram. Use when Garmin authentication fails (HTTP 401, expired tokens) or when the user asks to log into Garmin.
|
|
---
|
|
|
|
# 🔐 Garmin Connect Authentication & MFA Manager
|
|
|
|
Headless authentication lifecycle manager for Garmin Connect, allowing OpenClaw to initiate logins, keep tokens perpetually fresh, and verify 6-digit MFA codes directly via Telegram.
|
|
|
|
## 🎯 When to Use
|
|
- **Authentication Errors**: Whenever a `garmin` MCP tool call fails with `Garmin authentication failed`, `Tokens expired`, `401 Unauthorized`, or `Failed to retrieve social profile`.
|
|
- **User Request**: Whenever the user explicitly asks: *"Logge dich bei Garmin ein"*, *"Garmin MFA Code eingeben"*, *"Garmin Re-Auth"*, *"Verbinde Garmin"*.
|
|
- **Keepalive / Watchdog**: During morning briefings or background checks to ensure tokens are proactively refreshed before expiring.
|
|
- **Status Checks**: Whenever asked about Garmin token health or expiration: *"Ist Garmin eingeloggt?"*, *"Wie lange ist der Garmin-Token noch gültig?"*.
|
|
|
|
---
|
|
|
|
## 🕹️ Interactive Telegram MFA Login Flow (Protocol)
|
|
|
|
Because Garmin requires Multi-Factor Authentication (OTP sent via SMS/email), login operates in **two conversation turns**:
|
|
|
|
### Turn 1: Request Code (Initiate Login)
|
|
1. Execute the `request-code` command:
|
|
```bash
|
|
uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py request-code
|
|
```
|
|
2. The command spawns a background authentication daemon and triggers Garmin to dispatch the 6-digit code to the user's email/SMS.
|
|
3. Immediately send a clear, friendly prompt to the user on Telegram:
|
|
> 🔑 **Garmin-Authentifizierung erforderlich**
|
|
> Ich habe einen neuen Login bei Garmin gestartet. Garmin hat dir soeben einen 6-stelligen Sicherheitscode per SMS oder E-Mail gesendet.
|
|
>
|
|
> Bitte antworte mir einfach kurz mit dem **6-stelligen Code**!
|
|
|
|
### Turn 2: Verify Code (Complete Login)
|
|
1. When the user sends a 6-digit message (e.g. `538291`, `538 291`):
|
|
2. Execute the `verify` command:
|
|
```bash
|
|
uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py verify "<mfa_code>"
|
|
```
|
|
3. If successful:
|
|
- The tokens are automatically dumped to `/home/node/.openclaw/garmin_tokens/garmin_tokens.json` and base64 exported.
|
|
- Reply to the user:
|
|
> ✅ **Garmin-Login erfolgreich!**
|
|
> Angemeldet als **Moritz Graf**. Alle Garmin-Tools und Workouts sind wieder voll einsatzbereit.
|
|
4. If the code was incorrect:
|
|
- The daemon remains alive for 5 minutes. Inform the user and allow them to retry:
|
|
> ⚠️ Der eingegebene Code war leider ungültig oder abgelaufen. Bitte prüfe den Code und sende ihn erneut.
|
|
|
|
---
|
|
|
|
## 🛠️ CLI Operations Reference
|
|
|
|
### 1. Check Token Health & Validity
|
|
```bash
|
|
uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py status
|
|
```
|
|
Outputs JSON with `valid`, `user`, `exp_utc`, `pending_mfa`.
|
|
|
|
### 2. Proactive Keepalive (Refresh Token before Expiry)
|
|
```bash
|
|
uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py keepalive
|
|
```
|
|
Touches the API, triggering `python-garminconnect`'s automatic token refresh and persisting the newly rotated refresh token to `/home/node/.openclaw/garmin_tokens/garmin_tokens.json`.
|
|
|
|
---
|
|
|
|
## 🔒 Security & Environment
|
|
- Requires `GARMIN_EMAIL` and `GARMIN_PASSWORD` (already injected via `openclaw-secrets`).
|
|
- Persistent storage: `/home/node/.openclaw/garmin_tokens/garmin_tokens.json` (on PVC `openclaw-data`).
|
|
- Directory permissions are automatically set to `0700` and files to `0600`.
|