|
| 1 | +# GitHub OAuth Device Flow Setup |
| 2 | + |
| 3 | +Blueprint Studio supports **OAuth Device Flow** for easy GitHub authentication! No manual token creation needed. |
| 4 | + |
| 5 | +## 🎉 Pre-Configured OAuth App (Recommended) |
| 6 | + |
| 7 | +**Good news!** Blueprint Studio comes with a **pre-configured shared OAuth app** that all users can use immediately. |
| 8 | + |
| 9 | +### ⚡ Just Click and Go! |
| 10 | + |
| 11 | +1. Click **"Login with GitHub OAuth"** in Git Settings |
| 12 | +2. Visit the URL and enter the code shown |
| 13 | +3. Authorize Blueprint Studio |
| 14 | +4. Done! You're logged in |
| 15 | + |
| 16 | +**No setup required** - the OAuth app is already configured for you! |
| 17 | + |
| 18 | +### 🔒 Is This Safe? |
| 19 | + |
| 20 | +Yes! This is the standard approach used by: |
| 21 | +- ✅ GitHub CLI (`gh`) |
| 22 | +- ✅ VSCode |
| 23 | +- ✅ Git Credential Manager |
| 24 | +- ✅ Many other tools |
| 25 | + |
| 26 | +The OAuth Client ID is **public and meant to be shared**. Each user still: |
| 27 | +- Authenticates with their own GitHub account |
| 28 | +- Gets their own private access token |
| 29 | +- Controls their own authorization |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## 🔧 Advanced: Using Your Own OAuth App (Optional) |
| 34 | + |
| 35 | +If you prefer to use your own GitHub OAuth app for privacy/security reasons, you can create one: |
| 36 | + |
| 37 | +### Step 1: Create a GitHub OAuth App |
| 38 | + |
| 39 | +1. Go to: https://github.com/settings/developers |
| 40 | +2. Click **"New OAuth App"** |
| 41 | +3. Fill in the details: |
| 42 | + - **Application name:** Blueprint Studio (or any name) |
| 43 | + - **Homepage URL:** `https://github.com/yourusername/repo` (or any URL) |
| 44 | + - **Authorization callback URL:** Leave blank or use `http://localhost` (not used by Device Flow) |
| 45 | + - **Application description:** (optional) |
| 46 | + |
| 47 | +4. Click **"Register application"** |
| 48 | + |
| 49 | +5. You'll see your **Client ID** - copy this (it looks like: `Ov23liXXXXXXXXXXXXXX`) |
| 50 | + |
| 51 | +6. **Important:** You do NOT need to generate a client secret for Device Flow! |
| 52 | + |
| 53 | +### Step 2: Configure Your Custom Client ID |
| 54 | + |
| 55 | +To use your own OAuth Client ID, you can set it via browser console: |
| 56 | + |
| 57 | +**Open Browser Console** (F12 or right-click → Inspect → Console): |
| 58 | +```javascript |
| 59 | +localStorage.setItem("githubOAuthClientId", "YOUR_CLIENT_ID_HERE"); |
| 60 | +``` |
| 61 | + |
| 62 | +Replace `YOUR_CLIENT_ID_HERE` with your actual Client ID. |
| 63 | + |
| 64 | +**That's it!** Next time you click "Login with GitHub OAuth", it will use your custom Client ID instead of the shared one. |
| 65 | + |
| 66 | +### Step 3: Use Your OAuth App |
| 67 | + |
| 68 | +After configuring your Client ID: |
| 69 | +1. Refresh Blueprint Studio |
| 70 | +2. Click "Login with GitHub OAuth" |
| 71 | +3. Authorize using your OAuth app |
| 72 | +4. Done! |
| 73 | + |
| 74 | +--- |
| 75 | + |
| 76 | +## 🔐 Security & Privacy |
| 77 | + |
| 78 | +### Default OAuth App |
| 79 | + |
| 80 | +- **Client ID is public** - This is normal and safe for OAuth Device Flow |
| 81 | +- **No client secret** - Device Flow doesn't use secrets |
| 82 | +- **Used by all Blueprint Studio users** - Shared OAuth app (like VSCode, GitHub CLI) |
| 83 | +- **Your credentials stay local** - Only stored on your Home Assistant instance |
| 84 | +- **No data sent to third parties** - Direct GitHub API communication only |
| 85 | + |
| 86 | +### Your Own OAuth App |
| 87 | + |
| 88 | +- **Full control** - You own and manage the OAuth app |
| 89 | +- **Private** - Only you use this OAuth app |
| 90 | +- **Same security** - OAuth Device Flow is equally secure |
| 91 | + |
| 92 | +--- |
| 93 | + |
| 94 | +## 📝 How OAuth Device Flow Works |
| 95 | + |
| 96 | +1. **Request Code:** Blueprint Studio asks GitHub for a device code and user code |
| 97 | +2. **Show Code:** You see a code like `ABCD-1234` |
| 98 | +3. **Authorize:** Visit GitHub and enter the code |
| 99 | +4. **Poll for Token:** Blueprint Studio polls GitHub for authorization |
| 100 | +5. **Get Token:** Once authorized, GitHub provides an access token |
| 101 | +6. **Save Token:** Token is saved persistently (same as PAT method) |
| 102 | +7. **Done:** You're logged in! |
| 103 | + |
| 104 | +**Technical Details:** |
| 105 | +- Uses GitHub's standard Device Flow API |
| 106 | +- No redirect URLs needed (perfect for local Home Assistant) |
| 107 | +- Works on any network (local, VPN, remote) |
| 108 | +- Token is saved with base64 encoding (same as PAT) |
| 109 | + |
| 110 | +--- |
| 111 | + |
| 112 | +## 🆚 PAT vs OAuth Device Flow Comparison |
| 113 | + |
| 114 | +| Feature | PAT Method | OAuth Device Flow | |
| 115 | +|---------|------------|-------------------| |
| 116 | +| **Setup Complexity** | Manual token creation | Click and authorize | |
| 117 | +| **User Experience** | Copy/paste token | Click and type code | |
| 118 | +| **Security** | Long-lived token | OAuth token (refreshable) | |
| 119 | +| **2FA Support** | Manual | Automatic | |
| 120 | +| **Token Visibility** | You see it | Hidden from user | |
| 121 | +| **Persistence** | ✅ Yes | ✅ Yes | |
| 122 | +| **OAuth App Required** | ❌ No | ⚠️ Yes (provided by default) | |
| 123 | + |
| 124 | +--- |
| 125 | + |
| 126 | +## 🐛 Troubleshooting |
| 127 | + |
| 128 | +### "Failed to start device flow" |
| 129 | + |
| 130 | +**Cause:** Cannot reach GitHub's OAuth API |
| 131 | + |
| 132 | +**Solutions:** |
| 133 | +- Check your internet connection |
| 134 | +- Verify Home Assistant can reach github.com |
| 135 | +- Check firewall settings |
| 136 | + |
| 137 | +### "Login expired" |
| 138 | + |
| 139 | +**Cause:** Took too long to authorize (usually 15 minutes) |
| 140 | + |
| 141 | +**Solutions:** |
| 142 | +- Click "Login with GitHub" again |
| 143 | +- Authorize faster (code expires in 15 min) |
| 144 | + |
| 145 | +### "Access denied" |
| 146 | + |
| 147 | +**Cause:** You clicked "Cancel" or denied authorization on GitHub |
| 148 | + |
| 149 | +**Solutions:** |
| 150 | +- Click "Login with GitHub" again |
| 151 | +- Accept the authorization on GitHub |
| 152 | + |
| 153 | +### "Invalid client_id" |
| 154 | + |
| 155 | +**Cause:** Using a custom OAuth app with wrong Client ID |
| 156 | + |
| 157 | +**Solutions:** |
| 158 | +- Verify your Client ID is correct |
| 159 | +- Make sure you copied the full ID from GitHub |
| 160 | +- Try using the default OAuth app first |
| 161 | + |
| 162 | +--- |
| 163 | + |
| 164 | +## 🔄 Switching Between Methods |
| 165 | + |
| 166 | +You can switch between OAuth and PAT at any time: |
| 167 | + |
| 168 | +**From PAT to OAuth:** |
| 169 | +1. Open Git Settings |
| 170 | +2. Click "Login with GitHub" |
| 171 | +3. Authorize |
| 172 | +4. Your new OAuth token replaces the PAT |
| 173 | + |
| 174 | +**From OAuth to PAT:** |
| 175 | +1. Open Git Settings |
| 176 | +2. Scroll to "Manual PAT Configuration" |
| 177 | +3. Enter username and PAT token |
| 178 | +4. Click "Save Credentials" |
| 179 | +5. Your new PAT replaces the OAuth token |
| 180 | + |
| 181 | +**Note:** Only one set of credentials is stored at a time. |
| 182 | + |
| 183 | +--- |
| 184 | + |
| 185 | +## 📚 Additional Resources |
| 186 | + |
| 187 | +- **GitHub Device Flow Docs:** https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#device-flow |
| 188 | +- **Creating PAT Tokens:** https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token |
| 189 | +- **OAuth Best Practices:** https://docs.github.com/en/developers/apps/building-oauth-apps/best-practices-for-oauth-apps |
| 190 | + |
| 191 | +--- |
| 192 | + |
| 193 | +## ✨ Benefits Over PAT |
| 194 | + |
| 195 | +1. **Easier for new users** - No need to navigate GitHub settings |
| 196 | +2. **Better UX** - Click, code, done |
| 197 | +3. **More secure** - No manual token handling |
| 198 | +4. **Works with 2FA** - No special setup needed |
| 199 | +5. **Standard OAuth** - Same flow as VSCode, GitHub CLI, etc. |
| 200 | + |
| 201 | +--- |
| 202 | + |
| 203 | +## 💡 FAQ |
| 204 | + |
| 205 | +**Q: Do I need to create an OAuth app?** |
| 206 | +A: No! Blueprint Studio provides a pre-configured shared OAuth app for all users. |
| 207 | + |
| 208 | +**Q: Can I use my own OAuth app?** |
| 209 | +A: Yes! Use browser console to set your custom Client ID (instructions above). |
| 210 | + |
| 211 | +**Q: Is the shared OAuth app safe?** |
| 212 | +A: Yes! This is the standard approach used by GitHub CLI, VSCode, and many other tools. Your credentials stay private on your Home Assistant instance. |
| 213 | + |
| 214 | +**Q: Is OAuth more secure than PAT?** |
| 215 | +A: Both are secure. OAuth has better UX and works better with 2FA. |
| 216 | + |
| 217 | +**Q: Will my credentials persist after restart?** |
| 218 | +A: Yes! Both PAT and OAuth tokens are saved persistently. |
| 219 | + |
| 220 | +**Q: Can I switch between PAT and OAuth?** |
| 221 | +A: Yes! You can switch at any time in Git Settings. |
| 222 | + |
| 223 | +**Q: What happens to the old token when I switch?** |
| 224 | +A: It's replaced with the new one. Old token is deleted. |
| 225 | + |
| 226 | +**Q: Where are credentials stored?** |
| 227 | +A: In `.storage/blueprint_studio.credentials` on your Home Assistant instance (encrypted by Home Assistant). |
| 228 | + |
| 229 | +**Q: Can I revoke access?** |
| 230 | +A: Yes! Go to GitHub Settings → Applications → Blueprint Studio → Revoke |
| 231 | + |
| 232 | +--- |
| 233 | + |
| 234 | +## 🎉 Enjoy Easy GitHub Authentication! |
| 235 | + |
| 236 | +No more manually creating PAT tokens! Just click "Login with GitHub" and you're done. |
| 237 | + |
| 238 | +Happy coding! 🚀 |
0 commit comments