OAuth refresh token files production credentials क्यों हैं?

कॉपी की गई auth.json file कोई setup का बेकार अवशेष नहीं है। अगर उसमें refresh token है, तो वह production credential है, जो उस व्यक्ति के घर चले जाने के बाद भी access tokens बनाता रह सकता है जिसने उसे कॉपी किया था। Machine को headless कहने से यह बात नहीं बदलती। इससे केवल browser prompt हट जाता है, जो किसी को ownership के बारे में सोचने की याद दिलाता।

मैंने teams को API key की सावधानी से सुरक्षा करते देखा है, फिर access token जल्दी expire हो जाने के कारण refresh-token file को chat attachment के रूप में build host पर भेजते देखा है। यह उलटा है। Short-lived access token आमतौर पर file का सबसे महत्वपूर्ण हिस्सा नहीं होता। Renewal path वह हिस्सा है जिसे attacker, जरूरत से ज्यादा permissions वाला agent या बिना जवाबदेही वाला overnight job लगातार इस्तेमाल कर सकता है।

Refresh token file credential package है

OAuth refresh token file credential package है, क्योंकि उसमें आमतौर पर इतना state होता है कि बिना किसी इंसान के मौजूद हुए नया bearer token लिया जा सके। Exact fields client library के अनुसार बदलते हैं, लेकिन खतरनाक combination जाना-पहचाना है: refresh token, client identifier, token endpoint, granted scopes और कभी-कभी client secret या device-specific assertion।

File extension को देखकर जोखिम को छोटा न समझें। JSON केवल एक envelope है। .cache/session.json, token-store.json या auth.json नाम की file को private SSH key जैसी ही सुरक्षा मिलनी चाहिए, अगर वह production service का access renew कर सकती है।

OAuth 2.0 Authorization Framework, RFC 6749, refresh tokens को access tokens पाने के लिए इस्तेमाल होने वाले credentials के रूप में बताता है। उसमें यह भी कहा गया है कि authorization server नया refresh token जारी कर सकता है और client को पुराने token को discard करना चाहिए। Protocol detail समझकर इस आखिरी बात को टालना आसान है। Unattended system में यह operational requirement है: एक ही credential file रखने वाले दो workers अब उसकी identity को लेकर आपस में race कर सकते हैं।

Inventory में इन तीन चीजों को अलग-अलग दर्ज करें:

• Access token सीमित अवधि के लिए request को authorize करता है।
• Refresh token renewal को authorize करता है, अक्सर कई access-token lifetimes तक।
• OAuth client उस software की पहचान बताता है जो renewal मांग रहा है।

Teams अक्सर पहले दो को एक ही चीज समझ लेती हैं और फिर expiry को लेकर गलत तर्क देती हैं। पांच मिनट का access token किसी copied refresh token को सुरक्षित नहीं बनाता। इसका मतलब सिर्फ इतना हो सकता है कि copied file intruder को पांच-पांच मिनट के batches में नए tokens देती रहे।

Production inventory entry को सिर्फ «यह किस service में इस्तेमाल होती है?» का जवाब नहीं देना चाहिए। Authorization server, OAuth client identifier, resource server, subject या service account, exact granted scopes, environment, उपलब्ध होने पर issuance time, renewal owner, approved execution path और revocation method दर्ज करें। अगर ये fields भरी नहीं जा सकतीं, तो credential autonomous use के लिए तैयार नहीं है। आपके पास testing में काम कर चुकी एक file है।

Headless काम में ownership आसानी से खो जाती है

Headless agent के renewal arrangement में जवाबदेह owner का नाम होना चाहिए। आमतौर पर समस्या तब शुरू होती है, जब developer अपने personal account से local tool को authorize करता है और फिर server पर उसका cache कॉपी कर देता है, क्योंकि server browser flow पूरा नहीं कर सकता। Job चलती रहती है, इसलिए वह copy स्थायी बन जाती है।

अब उन सवालों पर ध्यान दें जिन्हें लोग असहज होने के कारण छोड़ देते हैं। Token developer, team या job में से किसका प्रतिनिधित्व करता है? इसे किसका काम तोड़े बिना revoke किया जा सकता है? कौन-सा repository या agent instruction job को बताता है कि इसे कहां ढूंढना है? क्या employee के जाने के बाद उसके पीछे की identity invalidate की जा सकती है? Provider का consent page personal account दिखाता है, जबकि job service की तरह काम करती है?

«Platform account इसका owner है» कोई जवाब नहीं है, जब तक उस account के लिए documented administrator, recovery procedure और limited privileges मौजूद न हों। Personal login से कॉपी किया गया token एक visible API key से एक मायने में ज्यादा जोखिम भरा है: वह अक्सर opaque cache file के रूप में आता है, इसलिए reviewers देख नहीं पाते कि उसके साथ कौन-सी permissions आ गईं।

जहां provider support करता हो, dedicated service identity इस्तेमाल करें। उस identity को वही resource permissions दें जिनसे job पूरी हो सके। Development, staging और production जैसी meaningful trust boundaries के लिए अलग OAuth client register करें। Renewal आसान बनाने के लिए एक broad client और broad consent grant का इस्तेमाल न करें।

एक फर्क स्पष्ट रखना जरूरी है: OAuth client identity और resource identity अलग controls हैं। Client identifier बताता है कि token के लिए किस software ने request की। Subject और scopes बताते हैं कि token किन resources तक पहुंच सकता है और क्या कर सकता है। Dedicated client बनाने के बाद भी उसे human administrator के रूप में authorize करने वाली team ने attribution थोड़ा सुधारा है, लेकिन privilege की समस्या जस की तस है।

Agent के लिए deployment documentation के पास एक सरल ownership record लिखें, token file के अंदर नहीं:

Credential name: billing-export-prod
OAuth client: agent-billing-prod
Resource identity: svc-billing-export
Scopes: reports.read, exports.write
Renewal owner: platform-oncall
Execution path: production job runner through credential broker
Revocation: authorization server admin console and RFC 7009 endpoint

यह record जान-बूझकर उबाऊ है। इसी वजह से रात के दो बजे यह काम आता है। Operator बिना अंदाजा लगाए सही grant revoke कर सकता है और समझ सकता है कि file developer के पुराने laptop, staging test या उस job की थी जिसने अब उसे page किया है।

Renewal path को agent workspace से बाहर रखें

Agent process को refresh token file पढ़नी ही नहीं चाहिए। अगर agent उस string को पढ़ सकता है, तो वह उसे print कर सकता है, log में लिख सकता है, patch में embed कर सकता है, remote tool को भेज सकता है या crash report में छोड़ सकता है। Disclosure रोकने वाली prompt instructions उस data को exfiltrate करने की process की क्षमता नहीं बदलतीं जिसे वह पढ़ सकती है।

Filesystem permissions फिर भी महत्वपूर्ण हैं, लेकिन architectural choice के बाद वे containment layer हैं। Conventional Unix host पर 0600 जैसा file mode दूसरे local accounts को बाहर रखता है। इससे authorized agent process, उसके plugins, child processes, debugger या backup job file को पढ़ने से नहीं रुकते। यह भी स्पष्ट नहीं होता कि उस host में production renewal credential रखा ही क्यों गया है।

Refresh token को secret manager, operating-system credential store या ऐसे local broker में रखें जो agent से raw values का अनुरोध स्वीकार न करे। Broker को narrow action request लेनी चाहिए, credential को internally fetch या refresh करना चाहिए, approved resource endpoint को call करना चाहिए और agent को केवल जरूरी result लौटाना चाहिए। Request कुछ ऐसी दिख सकती है:

{
  "action": "create_export",
  "target": "billing-api",
  "parameters": {
    "report_date": "2026-07-23"
  }
}

Agent को token के बजाय ऐसा response मिलना चाहिए:

{
  "status": "accepted",
  "export_id": "exp_4821",
  "report_date": "2026-07-23"
}

यह boundary एक आम गलती रोकती है: हर job container में secret directory mount करके उसे controlled access कहना। Mount उस container के अंदर मौजूद हर library, shell command, extension और accidental diagnostic dump के लिए secret उपलब्ध करा देता है। Broker unknown targets को reject कर सकता है, खुद सही credential जोड़ सकता है और renewal state को agent memory से बाहर रख सकता है।

macOS पर Sallyport अपने supported HTTP और SSH actions के लिए इसी pattern का पालन करता है: credentials उसके encrypted vault में रहते हैं और agent को plaintext secrets के बजाय action results मिलते हैं। यह design उपयोगी है, क्योंकि इसमें authorize करने वाली चीज token file की सुविधा नहीं, बल्कि request होती है।

Refresh-token files को repository directories, CI workspaces, shared network folders, home-directory dotfiles, container images या generic backup paths में न रखें। हर location copying का अलग रास्ता बनाती है और हर copy भविष्य में revocation की एक नई समस्या जोड़ती है। अगर कोई legacy tool path पर निर्भर है, तो उसे credential helper के ownership वाली short-lived, isolated runtime directory दें। File बनाने और हटाने की जिम्मेदारी helper की हो। इसे expiry date वाले compatibility exception की तरह देखें, standard pattern की तरह नहीं।

Scopes एक job का वर्णन करें, department का नहीं

Headless agent के scopes उसके एक job का वर्णन करने चाहिए। अगर agent को कभी किसी दूसरे project की जरूरत पड़ सकती है, इसलिए हर project पढ़ने की अनुमति वाला token आखिरकार ऐसे context में इस्तेमाल होगा जिसकी किसी ने कल्पना नहीं की थी। Broad scope लोकप्रिय है, क्योंकि authorization screens और provider documentation परेशान कर सकते हैं। इसकी कीमत incident के समय चुकानी पड़ती है, जब एक automation token revoke करने से असंबंधित काम भी रुक जाता है।

Provider की उपलब्ध scopes की list से शुरुआत न करें। अंतिम API calls से शुरुआत करें। Job को किन verbs और resources की जरूरत है, लिखें। Invoices fetch करने और पूरा export upload करने वाली job को invoices के लिए read access और export location के लिए write access चाहिए हो सकता है। उसे user administration, repository deletion, billing changes या permission-management scopes की जरूरत नहीं है, सिर्फ इसलिए कि initial setup के दौरान किसी व्यक्ति ने इन permissions का इस्तेमाल किया था।

OAuth scopes अकेले पर्याप्त नहीं हैं। Resource-side permissions मामूली दिखने वाले scope का असर बढ़ा सकती हैं। files.write वाला token भी बड़े estate को नुकसान पहुंचा सकता है, अगर उसके subject को हर team folder का access हो। जहां provider अनुमति देता हो, service identity को सीमित project, folder, organization unit या repository से जोड़ें। फिर negative cases test करें: adjacent production resource पर action permission के कारण fail होना चाहिए, केवल इसलिए नहीं कि agent ने अभी तक उसे आजमाया नहीं है।

अलग duties के लिए अलग grants बनाएं, भले provider combined list स्वीकार करता हो। उदाहरण के लिए, read-only data collection job को results publish करने वाली job से अलग रखें। Leaked publisher credential का असर, rotation rhythm और approval owner reader से अलग होते हैं। दोनों को मिलाने से एक token renewal flow बचता है, लेकिन हर investigation कठिन हो जाती है।

Human administrator के session पर आधारित scope patterns से बचें। Administrators setup के लिए broad permissions को consent कर लेते हैं। Running agent administrator का judgment नहीं लेता। उसे केवल administrator की authorization मिलती है।

एक उपयोगी review test यह है: consent record पढ़ें और job को एक वाक्य में बताने की कोशिश करें। अगर विवरण «यह कई ऐसी चीजें manage कर सकता है जिनकी हमें जरूरत पड़ सकती है» बन जाता है, तो grant तैयार नहीं है। Job को सीमित करें या उसे अलग grants में बांटें। दो credentials maintain करने की असुविधा उस स्थिति से सस्ती है जिसमें पता चले कि export agent identity settings बदल सकता है।

Self-refreshing tokens के लिए एक serial owner चाहिए

Refresh token rotation state-management की समस्या पैदा करता है और unattended workers को इसे सोच-समझकर हल करना पड़ता है। कई authorization servers refresh tokens rotate करते हैं: सफल refresh के बाद server replacement भेजता है और पिछले token को invalid कर सकता है। RFC 9700, OAuth 2.0 Security Best Current Practice, replay का पता लगाने के लिए public clients में refresh token rotation या sender-constrained refresh tokens की सलाह देता है। यह अच्छी security recommendation है, लेकिन shared file को सुरक्षित नहीं बनाती।

एक आम failure पर विचार करें। Worker A और worker B एक ही mounted auth.json से शुरू होते हैं। Worker A पहले refresh करता है और R2 पाता है। Provider R1 को invalid कर देता है। A के R2 लिखने से पहले process बंद हो जाता है या filesystem write उस local layer पर होती है जिसे B देख नहीं सकता। Worker B R1 भेजता है, invalid_grant पाता है और retry करता है। Operator failed job देखकर backup से पुराना cache कॉपी कर देता है। अब incident response ने और credential copies बना दी हैं।

इनमें से कोई एक arrangement अपनाएं:

1. एक credential broker refreshes का owner हो और replacement को transactionally store करे।
2. कोई एक scheduled worker किसी particular grant का owner हो, स्पष्ट lock के साथ और token state share करने वाली parallel replicas के बिना।
3. अलग workers के लिए अलग grants हों, ताकि हर refresh token का एक ही writer हो।

पहला arrangement आमतौर पर सबसे साफ रहता है। दूसरा छोटे, नियंत्रित job के लिए काम कर सकता है, लेकिन lock expiry और crash recovery को वास्तविक design की जरूरत होगी। तीसरे में consent और lifecycle work ज्यादा लगता है, फिर भी failures अच्छी तरह सीमित रहते हैं।

अगर provider rotation बंद करने की सुविधा देता हो, तो race हल करने के लिए उसे बंद न करें। यह recommendation आकर्षक लगती है, क्योंकि इससे concurrency bug छिप जाता है। इससे चोरी हुए refresh token को बिना पकड़े ज्यादा देर तक काम करने का मौका भी मिलता है। Ownership model ठीक करें।

Persistence path को नया token atomically update करना चाहिए और stale writer का पता लगाने के लिए पर्याप्त metadata बचाना चाहिए। कम से कम version, आखिरी सफल refresh time और ऐसा stable credential identifier store करें जिसे log करना सुरक्षित हो। Secret store को version 14 को replace करने वाले update को तब reject करना चाहिए, जब version 15 पहले से मौजूद हो। साधारण overwrite से slow worker stale state को फिर से जीवित कर सकता है।

जब authorization server sender-constrained tokens देता हो, तो समझें कि binding किस चीज से है। Proof mechanism संबंधित client-held key के बिना copied token को कम उपयोगी बना सकता है। यह उस key के आसपास access control का विकल्प नहीं है और human consent grant को proper service identity में नहीं बदलता। इसे एक और barrier मानें, cache files बांटने का कारण नहीं।

Rotation calendar reminder नहीं, runbook है

Rotation policy तभी विश्वसनीय है, जब कोई व्यक्ति बिना improvisation के उसे चला सके। Calendar-based rotation की अपनी जगह है, लेकिन ownership change, suspicious activity, host compromise, repository exposure और unexpected invalid_grant errors उसी तैयार sequence को trigger करने चाहिए। Copied token के बाहर निकलने का संदेह हो तो scheduled date का इंतजार न करें।

एक workable runbook में पांच actions होते हैं:

1. प्रभावित agent या broker path को freeze करें, ताकि बदलाव के दौरान वह refresh करता न रहे।
2. Ownership record और logs से OAuth client, resource identity, scopes और credential version की पहचान करें।
3. Authorization server पर refresh token या grant revoke करें। जहां उपलब्ध हो, provider के console या उसके RFC 7009-compatible revocation endpoint का इस्तेमाल करें।
4. हर ज्ञात runtime copy हटाएं और ऐसे backup या cache process को invalidate करें जो उसे वापस ला सकता है।
5. Dedicated identity को फिर से enroll करें, minimum allowed action test करें और replacement version दर्ज करें।

RFC 7009 token revocation को define करता है और servers को request संभालते समय संबंधित tokens और grants revoke करने की अनुमति देता है। इसलिए revoke दबाने से पहले operator को blast radius पता होना चाहिए। Provider current access token, refresh token family या पूरा grant invalidate कर सकता है। सही प्रतिक्रिया revocation से बचना नहीं है। सही प्रतिक्रिया यह document करना है कि कौन-सी jobs एक grant share करती हैं, ताकि वे गलती से एक grant share न करें।

Disposable non-production identity के साथ rotation test करें। Confirm करें कि नया replacement काम करता है, पुराना token fail होता है और stale worker नई state overwrite नहीं कर सकता। फिर revoked-token response का अभ्यास करें। Job को recognizable error और ticket में दर्ज की जा सकने वाली identity के साथ fail closed होना चाहिए, developer के cached login पर चुपचाप fallback नहीं करना चाहिए।

Backups को विशेष handling चाहिए। Encrypted backups भी retention period खत्म होने तक refresh token को सुरक्षित रखते हैं। Historical backup blocks तुरंत delete करना संभव न हो, फिर भी exposed grant को तुरंत revoke किया जा सकता है। Retention location document करें, ताकि investigator जान सके कि recovery media में obsolete secret मौजूद है, भले ही वह अब काम न करता हो।

Actions और renewal events को अलग-अलग audit करें

Audit logs में renewal events और resulting access tokens से किए गए actions दोनों दिखने चाहिए। Refresh event बताता है कि credential active रहा। यह नहीं बताता कि agent ने एक report पढ़ी या हजार records बदल दिए। दूसरी ओर, credential version के बिना API action log से यह पता लगाना संभव नहीं रहता कि उसे किस renewal path ने authorize किया।

हर refresh के लिए safe metadata record करें: timestamp, credential identifier, पहले और बाद का token version, OAuth client identifier, subject identifier, provider expose करे तो requested या returned scope, execution host या broker identity और outcome। हर protected action के लिए safe metadata record करें: agent session या job identifier, requested target, operation, resource identifier, authorization decision, result code और correlation identifier।

Refresh token, access token, authorization code, client secret, full callback URL या raw Authorization header को कभी log न करें। Logging के बाद redaction करना देर हो जाती है, अगर collector, terminal recorder या error monitor event पा चुका हो। ऐसे logging calls बनाएं जो इन fields को स्वीकार ही न करें, बजाय इसके कि हर caller scrubber याद रखे।

एक उपयोगी incident query resource action से पीछे की ओर चलती है। मान लें कि export गलत destination पर दिखाई दिया। आप यह बता सकें: किस job ने request की, job किस process ने चलाई, उसने कौन-सा OAuth client इस्तेमाल किया, access किस credential version से मिला, वह version कब issue हुआ और क्या किसी दूसरे host ने उसी version का इस्तेमाल किया। अगर किसी link के लिए token value पढ़नी पड़े, तो audit design खराब है।

Agents लगातार supervision के बिना काम करते हों तो tamper evidence महत्वपूर्ण है। उसी host पर append-only log, silence से बेहतर है, लेकिन host पर नियंत्रण रखने वाला attacker cache और record दोनों बदल सकता है। Audit data को protected system में रखें और उसकी integrity independently verify करें। जो systems encrypted, hash-chained record रख सकते हैं, उनमें offline verification investigator को यह जांचने का तरीका देती है कि entries बदली गईं या नहीं, बिना underlying secrets उजागर किए।

Approval token exposure पर नहीं, actions पर रखें

Human approval सबसे उपयोगी उस boundary पर होती है जहां agent किसी outside system को प्रभावित करने की कोशिश करता है। किसी व्यक्ति से एक बार refresh-token file approve करवाकर कई हफ्तों तक किसी भी process को उसका इस्तेमाल करने देना control का आभास देता है, लेकिन sensitive string को circulation में डाल देता है।

Approvals को consequence के आधार पर चुनें। Read-only retrieval narrowly scoped, pre-approved session में चल सकता है। नए destination पर data भेजना, permissions बदलना, resource delete करना या credential को उसके usual job से बाहर इस्तेमाल करना human decision के लिए रुकना चाहिए। Approver को requesting process, target, operation और effect समझने के लिए पर्याप्त parameters दिखने चाहिए। सामान्य «allow OAuth» prompt लगभग बेकार है।

Frequent prompts को safety न समझें। अगर हर harmless call consent मांगेगी, तो लोग muscle memory से approve करेंगे। Routine work के लिए sensible session boundary रखें और high-consequence operations के लिए अलग approval मांगें। Agent kitchen table पर, travel connection पर या overnight job में चल रहा हो, तब भी decision दिखाई देना चाहिए।

Test सरल है: अगर agent instruction hostile हो जाए या plugin खराब व्यवहार करे, तो क्या वह ऐसे control को पार किए बिना outside-world action कर सकता है जिसमें किसी human को दिखे कि क्या होने वाला है? अगर जवाब हां है क्योंकि उसके पास पहले से auth.json है, तो credential को broker के पीछे रखें और request surface को फिर से design करें।

Legacy auth.json files को migration project मानें

Existing token caches एक दोपहर में शायद ही खत्म हों, लेकिन migration असुविधाजनक है इसलिए उन्हें undocumented छोड़ना उन्हें स्थायी बनाने का पक्का तरीका है। हर consumer खोजकर शुरुआत करें, फिर file को service, subject, scopes, environment, writer count और storage path के आधार पर classify करें। जिन copies का owner पता नहीं है उन्हें revoke करें। जिस token का कोई owner नहीं, उसे अपने-आप renew होने का अधिकार नहीं होना चाहिए।

एक बार में एक workflow move करें। पहले dedicated resource identity और client बनाएं। फिर उसका refresh token चुने गए secret store या broker के पीछे रखें। इसके बाद job को allowed action request submit करने के लिए बदलें और नए audit record की तुलना पुराने job output से करें। Replacement के काम करने के बाद ही legacy personal grant revoke करें।

कुछ tools आपका साथ नहीं देंगे। कुछ SDK मानते हैं कि local JSON cache उनका अपना है और उसे देखते ही चुपचाप refresh करने लगते हैं। ऐसे tools को constrained compatibility wrapper में रखें, जहां केवल एक process file पढ़ सके और agent को general access न हो। उस wrapper को हटाने का काम service owner की work queue में डालें। «Library इसे अपेक्षित मानती है» temporary exception को समझाता है, permanent secret leak path को सही नहीं ठहराता।

पहला migration target वह file होनी चाहिए जिसका scope सबसे broad है या जिसका owner सबसे कम स्पष्ट है, न कि वह जिसे move करना सबसे आसान है। यही वे credentials हैं जो agent की एक सीमित गलती को production incident में बदल सकते हैं। एक workflow को साफ तरीके से move करने के बाद deployment review, template changes और agent runtimes में raw credential caches mount करने से इनकार के जरिए पुराने pattern को दोहराना कठिन बनाएं।

Refresh token का एक जवाबदेह owner, एक controlled renewal path और हर outside action का नाम बताने वाला audit trail होना चाहिए जिसे उसने authorize किया है। अगर आपकी मौजूदा auth.json इन शर्तों को पूरा नहीं कर सकती, तो replacement path के काम करने की पुष्टि के बाद उसे revoke करें।