مرجع Control Center Connect
Control Center Connect ورود به ارائهدهندگان را برای سرورهایی اجرا میکند که برنامههای
خودشان را ثبت نکردهاند. یک سرور یا از Connect میزبانیشدهٔ Control Center استفاده میکند، یا
از Connectی که سازمانش اجرا میکند (اجرای سرور Connect)،
یا هیچکدام. انتخاب در تنظیمات ← سرور ← ورود یکپارچه ← Control Center Connect،
دستور cc_server connect، یا CC_CONNECT_URL قرار دارد. یک فضای کاری این انتخاب را دنبال میکند، مگر اینکه یک مدیر برای آن فضای کاری چیز دیگری در تنظیمات ← فضای کاری ← یکپارچهسازیها انتخاب کند (انتخاب هر فضای کاری).
مسیرها
بخش با عنوان “مسیرها”هر ارائهدهنده یک مسیر (lane) است. تحت استفاده از برنامههای خودم (یا پیش از انتخاب کسی)، مسیری روی برنامهٔ خود سرور اجرا میشود وقتی کاملاً پیکربندی شده باشد؛ در غیر این صورت غیرقابلدسترس است. با Control Center یا Connect سفارشی، Connect هر مسیری را که ارائه میدهد اجرا میکند: برنامههای خود سرور ذخیره میمانند اما برای ورود، برای خودکارسازی سرور یا برای وضعیت گزارششده استفاده نمیشوند. فضای کاریای که انتخاب خودش را کرده، بهجای آن هر مسیر را بر پایهٔ همان انتخاب اجرا میکند.
| مسیر | برنامهٔ خودی لازم دارد | از طریق Connect |
|---|---|---|
github |
App id، private key، client id و client secret | افراد با GitHub App مشترک وارد میشوند |
google |
Client id و client secret | افراد Google Calendar را متصل میکنند |
linear |
Client id | افراد با Linear وارد میشوند |
linear_app |
Client id | مدیر فضای کاری actor برنامهٔ Linear را متصل میکند |
slack |
اتصال برنامهٔ Slack خودِ فضای کاری | مدیر فضای کاری Slack را به برنامهٔ مشترک Slack متصل میکند |
klipy |
KLIPY_APP_KEY |
جستوجوی GIF که Connect آن را واسطه میکند |
برنامهٔ خودی که فقط تا حدی پیکربندی شده، مسیرش را خطا میکند، و هرگز بیسروصدا به Connect برنمیگردد. فضای کاریای که استفاده از برنامههای خودم را انتخاب کرده، هرگز برای هیچ ارائهدهندهای از برنامهٔ سرور یا Connect عبور نمیکند. تغییر انتخاب Connect سرور هیچکس را از فضای کاریای که انتخاب خودش را کرده خارج نمیکند.
آنچه Connect میبیند و آنچه هرگز نمیبیند
بخش با عنوان “آنچه Connect میبیند و آنچه هرگز نمیبیند”| Connect میبیند | Connect هرگز نمیبیند |
|---|---|
| شناسهٔ نصب سرور و امضای درخواستها | کد منبع، محتوای مخزن، diff یا متن درخواستهای pull |
| حساب ارائهدهندهای که در همان ورود وارد شده است | تیکتها، رونوشتها یا هر چیزی در پایگاهدادههای یک فضای کاری |
| اینکه اعتبارنامه به کدام فضای کاری تعلق دارد، بهصورت یک شناسهٔ مبهم داخل مهر | رازهای برنامهٔ خود سرور: هرگز سرور را ترک نمیکنند |
| مخزنی که برایش یک توکن GitHub تکمخزنی صادر میشود | توکنهای تازهسازی در حالت ذخیرهشده: فقط داخل مهرهایی وجود دارند که سرور نگه میدارد |
| تیم Slack که به سرور متصل است | رازهای Linear: سرور کد Linear را خودش مبادله میکند |
| عبارتهای جستوجوی GIF، وقتی Klipy را واسطه میکند | گذرواژهها، کلیدهای جفتسازی یا کلیدهای ارائهدهندهٔ مدل |
| ارجاعات رویداد Slack (تیم، کانال، شناسهٔ پیام) و متن دستورهای اسلش | متن پیامهای Slack: Connect آن را هنگام رسیدن دور میریزد و سرور خودش پیام را از Slack میخواند |
Connect ورودهای در حال انجام، nonceها و کشها را حداکثر ۱۰ دقیقه، و شمارندههای استفادهٔ ساعتی را حداکثر دو ساعت نگه میدارد. یک توکن GitHub تکمخزنی که بهعنوان یک فرد صادر شده، تا انقضایش (حداکثر ۸ ساعت) ثبت میماند، و به ورودی که آن را خواسته مهروموم است، تا Connect بتواند دوباره آن را تحویل دهد و هنگام قطع اتصال باطلش کند. تنها سوابق ماندگارش اتصالهای Slack است (اینکه هر تیم Slack به کدام سرور وصل است) و شناسههای نصب بازنشسته. خطاها فقط یک کد حمل میکنند، هرگز پاسخ ارائهدهنده را. گزارشها شناسههای نصب را فقط بهصورت hash کلیددار ثبت میکنند، و یک توکن GitHub را فقط بهصورت hashed_token که لاگ حسابرسی سازمان GitHub برایش نشان میدهد، تا یک مالک سازمان بتواند این دو را تطبیق دهد.
حالتها
بخش با عنوان “حالتها”| حالت | تنظیم | رفتار |
|---|---|---|
| تنظیمنشده | سرور تازه | هیچ مسیری از Connect استفاده نمیکند. راهاندازی از مالک سرور میخواهد انتخاب کند |
hosted |
استفاده از برنامههای Control Center | https://connect.usectrl.dev، با پیکربندی امضاشدهٔ آفلاین. برنامههای خود سرور استفاده نمیشوند |
custom |
استفاده از سرور Connect سفارشی | یک Connect در نشانی HTTPS (فقط روی http برای loopback)، که در اولین استفاده معتبر شناخته میشود. برنامههای خود سرور استفاده نمیشوند |
off |
استفاده از برنامههای خودم | هیچ مسیری از Connect استفاده نمیکند. فقط برنامههای خودی افراد را وارد میکنند |
CC_CONNECT_URL در محیط یا .env سرور، انتخاب را قفل میکند: hosted، off یا یک نشانی
Connect. آنگاه تنظیمات قفل را نشان میدهد و نمیتواند آن را تغییر دهد.
این ساخت هیچ کلید پیکربندی hosted را کامپایل نمیکند، پس حالت hosted، hosted_unprovisioned
گزارش میدهد و هیچ مسیری را ارائه نمیکند. برنامههای خودی و Connect سفارشی کار میکنند.
Connect میزبانیشده در یک کانتینر واحد اجرا میشود. کلید مهرومومسازی آن و کلید خصوصی GitHub App مشترک در آنجا متغیرهای محیطیاند، نه کلیدهایی در یک گاوصندوق که فقط امضا یا رمزگشایی کند، همانطور که GitHub برای کلید خصوصی یک App توصیه میکند. این یک شکاف شناختهشده در پیکربندی فعلی است.
سرور حداکثر هر ۱۰ دقیقه پیکربندی Connect را میخواند و برای هر فراخوانی حداکثر ۵ ثانیه صبر میکند. وقتی Connect در دسترس نباشد، آخرین پیکربندی معتبر در استفاده میماند و تنظیمات آن را قدیمی علامت میزند.
انتخاب هر فضای کاری
بخش با عنوان “انتخاب هر فضای کاری”تنظیمات ← فضای کاری ← یکپارچهسازیها ← Control Center Connect انتخاب سرور را برای یک فضای کاری تغییر میدهد. همهٔ اعضا آن را میبینند و میبینند هر ورود کجا اجرا میشود؛ فقط مدیر فضای کاری آن را تغییر میدهد.
| انتخاب | رفتار |
|---|---|
| مانند این سرور | پیشفرض. فضای کاری روی هر انتخابی که مالک سرور کرده کار میکند؛ گزینه نام آن را نشان میدهد |
| استفاده از برنامههای Control Center | Connect میزبانیشدهٔ Control Center، هر آنچه سرور استفاده میکند |
| استفاده از برنامههای خودم | فقط برنامههای خود فضای کاری: GitHub App، کلاینت Google، برنامهٔ Linear، کلید Klipy و برنامهٔ Slack. ارائهدهندهای که یکی از آنها را ندارد اینجا خاموش است؛ برنامهای که فقط تا نیمه تنظیم شده خطای راهاندازی است |
| استفاده از سرور Connect سفارشی | یک Connect روی نشانی HTTPS که فضای کاری مشخص میکند. نشانیهای روی شبکهٔ خصوصی یا محلی رد میشوند |
- هر انتخابی بهجز مانند این سرور ورودهای GitHub و Linear هر فرد را در جایگاهی از خود فضای کاری نگه میدارد، تا هرگز با ورودهای سراسر سرور قاطی نشوند
- تغییر انتخاب اول میپرسد: همهٔ اعضای فضای کاری دوباره از طریق برنامههای جدید وارد GitHub، Linear و Google Calendar میشوند
- اتصال برنامهٔ Slack خود فضای کاری زیر هر انتخابی کار میکند؛ افزودن Control Center به Slack از انتخاب پیروی میکند
CC_CONNECT_URLفضای کاریها را هم از داشتن Connect خودشان قفل میکند: میتوانند از سرور پیروی کنند یا از برنامههای خودشان استفاده کنند- Connect سفارشی یک فضای کاری فقط در اولین استفاده برای همان فضای کاری مورد اعتماد است: اعتماد به برنامههای تازه آنجا هیچوقت آنچه سرور یا فضای کاری دیگری به آن اعتماد دارد را تغییر نمیدهد
هویت نصب
بخش با عنوان “هویت نصب”| مورد | معنی |
|---|---|
| کلید نصب | یک seed به طول ۳۲ بایت در فایل رازهای سرور (connect_install_key)، جدا از کلیدهای جفتسازی دستگاه |
| کلید هر Connect | یک کلید Ed25519 که از seed و نشانی Connect مشتق میشود. هر درخواست به Connect با آن امضا میشود (RFC 9421) |
| شناسهٔ نصب | ۲۶ کاراکتر که از آن کلید عمومی مشتق میشود. در تنظیمات و با cc_server connect status نمایش داده میشود |
همان سرور برای هر نشانی Connect شناسهٔ نصب متفاوتی دارد. شناسه فقط وقتی تغییر میکند که کلید چرخانده شود.
اعتبارنامههای مهرومومشده
بخش با عنوان “اعتبارنامههای مهرومومشده”ورود از طریق Connect یک مهر اعتبارنامه (credential seal) برمیگرداند: یک بلوک رمزنگاریشده که فقط Connectی که آن را ساخته میتواند بازش کند. این مهر به ارائهدهنده، نشانی Connect، شناسهٔ نصب، فضای کاری، حساب ارائهدهنده، برنامه و نسل راز گره خورده است.
- سرور مهر و شناسهٔ نصبی را که مهر برایش ساخته شده ذخیره میکند. توکنهای دسترسی در حافظه میمانند
- برای تازهسازی، سرور مهر را پس میفرستد و یک توکن دسترسی تازه و یک مهر تازه دریافت میکند
- مهری که شناسهٔ نصب یا نشانی Connect آن دیگر تطبیق نمیکند، هنگام خواندن بعدی حذف میشود و فرد دوباره وارد میشود. این پس از چرخش کلید، تغییر به Connect دیگر، یا بازیابی پوشهٔ داده روی سرور دیگر رخ میدهد
- مهری که Connect نتواند بازش کند با
access_deniedرد میشود
نصبهای GitHub
بخش با عنوان “نصبهای GitHub”هر سروری میتواند از یک نصب GitHub App مشترک استفاده کند. Connect هیچ ثبتی از اینکه کدام سرور اجازهٔ استفاده دارد نگه نمیدارد.
- Install GitHub App در تنظیمات ← فضای کاری ← یکپارچهسازیها صفحهٔ نصب برنامه را در GitHub باز میکند. سرور پیوند را از نام برنامه در پیکربندی Connect میسازد
- یک توکن تکمخزنی به نصب برنامه روی حساب مالک مخزن و به دسترسی فرد واردشده به آن مخزن نیاز دارد. این توکن خود همان فرد است، محدود به نقشش، و هرگز بیشتر
- یک سازمان Control Center را در GitHub محدود میکند: با حذف نصب، کوچککردن مخزنهایش یا حذف فرد
- برای فراخوانهایی که فقط خود فرد میتواند انجام دهد، مانند فهرستکردن نصبهایش، Connect به سرور توکن کاربری App خود فرد را میدهد، نه توکن تکمخزنی. وارد شدن روی یک سرور یعنی آن سرور را به آن توکن اعتماد دادن.
- سازمانی که فهرست مجاز IP در GitHub را اجرا میکند نمیتواند از Connect میزبانیشده استفاده کند، چون نشانیهایش ثابت نیستند. در عوض برنامهٔ GitHub خودش را روی سرورهایش یا روی یک Connect که اجرا میکند ثبت میکند.
- قطع اتصال فقط همان ورود را باطل میکند: Connect توکن تازهسازیاش را یک بار مصرف میکند و آنچه را برمیگرداند پاک میکند، و توکن کاربری خودش و توکنهای تکمخزنیای را که Connect برایش صادر کرده پاک میکند. هر نسخهای از مهرش که هرجا نگه داشته شده باشد از کار میافتد. ورودهای فرد روی سرورها و فضاهای کاری دیگر به کارشان ادامه میدهند. برای برداشتن کامل Control Center از یک حساب GitHub، آن را در GitHub زیر تنظیمات ← برنامهها ← برنامههای GitHub مجاز ← لغو لغو کنید
بات مشترک
بخش با عنوان “بات مشترک”توکنهایی که بهعنوان بات برنامه (as: app) صادر میشوند، برای هر سروری که از همان Connect استفاده میکند همان بات را در GitHub نشان میدهند: GitHub نمیتواند آن سرورها را از هم تشخیص دهد.
- هر سروری اجازه دارد بات بخواند و نظر بدهد:
read،reviewوcomment(دیدگاهها، برچسبها، مسئولان و واکنشها روی issue ها و pull requestها) - بازبینی یک pull request بهعنوان بات (
bot، که pull requestها را مینویسد) فقط برای سرورهایی مجاز است که اپراتور Connect درCONNECT_GITHUB_REVIEW_BOT_INSTALLSفهرست کرده است. به هر سرور دیگری پاسخneeds_requesterداده میشود و بازبینی با توکن خود فرد مسئول منتشر میشود، که GitHub آن را به همان فرد محدود میکند: بازبینی به نام او ظاهر میشود. این شامل انتشار بازبینی با هوش مصنوعی، نظرهای بازبینی و درخواست بازبینها میشود - push کردن، ساختن شاخه و باز کردن pull request (
write) هرگز بهعنوان بات مشترک صادر نمیشوند. همیشه از ورود خود درخواستکننده استفاده میکنند - تأیید یک pull request هرگز خودکار نیست، با هیچ توکنی
- سرور یا فضای کاریای که برنامهٔ GitHub خودش را دارد، بات را برای همهٔ این موارد نگه میدارد، از جمله بازبینیها
آنچه مالکان و اعضای سازمان باید بدانند
بخش با عنوان “آنچه مالکان و اعضای سازمان باید بدانند”- سروری که فردی روی آن وارد شده توکن کاربری App آن فرد را نگه میدارد: حداکثر ۸ ساعت برای هر توکن، که تا وقتی فرد اتصال را قطع کند تازه میشود. آن توکن میتواند بهجای او روی هر مخزنی عمل کند که برنامهٔ مشترک روی آن نصب است و او به آن دسترسی دارد. Connect میتواند یک سرور را برای همیشه قطع کند (یک نصب بازنشسته یا ردشده)، اما توکنی که از قبل تحویل داده شده تا انقضایش معتبر میماند
- نصب برنامهٔ مشترک GitHub روی یک سازمان برای هر سرور Control Center که هر عضوی روی آن وارد شود رضایت میدهد، نه فقط برای یک سرور
- بات مشترک است، همانطور که بالا گفته شد: یک سازمان در GitHub نمیتواند تشخیص دهد کدام سرور بهعنوان بات عمل کرده است
- سازمانی که مرز خودش را میخواهد، برنامهٔ GitHub خودش را ثبت میکند و Connect خودش را اجرا میکند (اجرای سرور Connect)، یا برنامه را روی سرورهای خودش پیکربندی میکند
اعتماد به پیکربندی
بخش با عنوان “اعتماد به پیکربندی”| Connect | سرور چگونه به پیکربندیاش اعتماد میکند |
|---|---|
| Hosted | امضای Ed25519 را در برابر کلیدهایی که در ساخت کامپایل شدهاند تأیید میکند. epochِ کمتر از بالاترین epochی را که دیده رد میکند (rollback) |
| Custom | app id و client id مربوط به GitHub، client id های Google و Linear، و شناسههای برنامه و کلاینت Slack را در اولین استفاده ثابت (pin) میکند. تغییر، ورودهای Connect را متوقف میکند (pins_changed) تا وقتی که مالک سرور اعتماد به برنامههای تازه را بزند |
عملیات
بخش با عنوان “عملیات”تنظیمات Connect خود سرور فقط برای مالک سرور است.
| عملیات | کار |
|---|---|
connect.status |
حالت، نشانی، قفل، شناسهٔ نصب، سلامت، epoch پیکربندی و منبع هر مسیر |
connect.configure |
hosted، custom (همراه با url) یا off را تنظیم میکند |
connect.test |
پیکربندی را دوباره میگیرد و سلامت را گزارش میکند |
connect.confirmPins |
شناسههای تغییرکردهٔ یک Connect سفارشی را میپذیرد |
connect.rotateKey |
یک کلید نصب تازه و یک شناسهٔ نصب تازه صادر میکند (force آن را جایگزین میکند حتی وقتی یک Connect نتواند شناسهٔ قدیمی را بازنشسته کند)؛ ببینید چرخش کلید نصب |
عملیات هر انتخاب فضای کاری عملیات خودش را دارد، که هرکدام نام فضای کاری را میبرند:
| عملیات | چه کسی | کار |
|---|---|---|
workspaceConnect.status |
هر عضو | انتخاب، آنچه به آن تبدیل میشود، سلامت و منبع هر ارائهدهنده. شناسهٔ نصب و سنجاقهای در انتظار فقط برای مدیران |
workspaceConnect.set |
مدیر فضای کاری | مقدار inherit، hosted، custom (با url) یا own را تنظیم میکند |
workspaceConnect.test |
مدیر فضای کاری | پیکربندی Connect فضای کاری را دوباره میگیرد و سلامت را گزارش میکند |
workspaceConnect.confirmPins |
مدیر فضای کاری | شناسههای تغییرکردهٔ Connect سفارشی فضای کاری را میپذیرد |
خود ورودها از oauth.lanes، oauth.begin، oauth.status، oauth.complete،
oauth.connections و oauth.disconnect استفاده میکنند. فرد همیشه همان فراخوان واردشده است.
ورود از طریق Connect
بخش با عنوان “ورود از طریق Connect”۱. سرور از Connect میخواهد مسیر را آغاز کند و نشانی authorize ارائهدهنده را دریافت میکند، که
پیش از نمایش آن را بررسی میکند. GitHub همیشه صفحهٔ انتخاب حساب خود را نشان میدهد
۲. فرد در مرورگر تأیید میکند. ارائهدهنده او را به Connect برمیگرداند
۳. Connect نشان میدهد سروری که ورود را آغاز کرده، بهجای فرد، چه کارهایی میتواند بکند و برای چه مدتی. Connect نمیتواند بفهمد چه کسی آن سرور را اجرا میکند، پس صفحه فقط وقتی از فرد میخواهد ادامه دهد که خودش ورود را آغاز کرده باشد، و اگر کسی پیوند را برایش فرستاده باشد، از او میخواهد آن را ببندد. وقتی مرورگر روی شبکهای جز شبکهٔ آغاز ورود باشد، صفحه این را میگوید: این برای یک سرور میزبانیشده یا دستگاه دیگری عادی است، و همین هم شکل فیشینگ است. لغو ورود را پایان میدهد: کد ارائهدهنده هرگز استفاده نمیشود. هر صفحه یک بار پاسخ میدهد؛ پاسخی که از صفحهای که Connect همان لحظه نشان داده نیامده باشد رد میشود
۴. پس از ادامه، Connect یک کد ۸ کاراکتری و پیوند control-center://oauth-done را نشان میدهد. هرکس کد را داشته باشد دسترسی تازهتأییدشده را میگیرد، پس فقط باید به جایی برود که ورود از آنجا آغاز شده
۵. فرد کد را در برنامه تایپ میکند یا پیوند را دنبال میکند. سرور ورود را با کد و اثبات خودش از
درخواست ادعا میکند
ورود پس از ۱۰ دقیقه منقضی میشود. پنج کد اشتباه آن را پایان میدهد. پیوندی که این برنامه آغاز
نکرده با این ورود از اینجا شروع نشده رد میشود. Connect تعداد ورودهایی را که یک نشانی شبکه میتواند آغاز کند، و دفعات صدور توکنهای GitHub را برای هر فرد و سرور، برای هر فرد در سراسر سرورها، برای هر نشانی، و برای کل برنامه محدود میکند. ورودهای تازه بودجهٔ خاص خودشان را دارند، پس هرگز تازهسازیهایی را که دیگران لازم دارند معطل نمیکنند. از هر حد که رد شود، یک فراخوان با rate_limited رد میشود و سرور بعداً دوباره امتحان میکند، بیآنکه کسی خارج شود. ورودی که از حد فرد بگذرد در GitHub لغو و رد میشود.
چرخش کلید نصب
بخش با عنوان “چرخش کلید نصب”فقط مالک سرور میتواند کلید را بچرخاند، با چرخش کلید روی کارت Control Center Connect در تنظیمات ← سرور ← ورود یکپارچه. برای آن دستوری وجود ندارد. چرخش:
- همه را از هر مسیری که از طریق Connect اجرا میشود خارج میکند. برای هر سرور Connect که کلید قدیمی با آن به کار میرفت، سرور ورودهای GitHub و Slackای را که از آنجا نگه میدارد باطل میکند (ورود Google چیزی برای باطلکردن ندارد و منقضی میشود)
- شناسهٔ نصب قدیمی را در هر یک از آن سرورهای Connect بازنشسته میکند، با امضای کلید قدیمی و اثبات با یک مهر اعتبارنامهای که سرور از آن Connect نگه میدارد. از آن پس Connect هر درخواستی را که با کلید قدیمی ساخته شده رد میکند، پس یک مهر یا یک نسخهٔ کلید قدیمی که از این سرور برداشته شده بیفایده است، و فضاهای کاری Slack که به شناسهٔ قدیمی وصل بودند آزاد میشوند تا دوباره وصل شوند. توکنهایی که از قبل تحویل داده شدهاند تا انقضایشان معتبر میمانند (یک ساعت برای توکن بات، هشت ساعت برای توکن فرد). Connect ای که این سرور از آن مهری ندارد چیزی برای بازنشستهکردن ندارد و رد میشود
- سپس به سرور یک کلید نصب تازه و یک شناسهٔ نصب تازه میدهد
- اگر یک سرور Connect در دسترس نباشد، یا از بازنشستهکردن شناسهٔ قدیمی خودداری کند، پیش از عوضکردن کلید متوقف میشود و Connect نتوانست کلید قدیمی را بازنشسته کند را نشان میدهد. با این حال بچرخان کلیدها را بیتوجه به آن عوض میکند؛ آنگاه شناسهٔ نصب قدیمی در آن Connect تا انقضای توکنهایش قابل استفاده میماند، که برای GitHub حداکثر ۸ ساعت است
- ورودها از طریق برنامههای خود سرور را بدون تغییر نگه میدارد
- نیاز دارد که شناسهٔ نصب جدید به فهرست مجاز یک Connect سفارشی اضافه شود
کدهای وضعیت
بخش با عنوان “کدهای وضعیت”| کد | معنی |
|---|---|
hosted_unprovisioned |
این ساخت کلید پیکربندی hosted ندارد |
signature |
امضای پیکربندی hosted بررسی را نگذراند |
rollback |
Connect پیکربندی قدیمیتر از آنچه سرور قبلاً دیده بود ارائه داد |
unreachable |
سرور نمیتواند به Connect برسد |
install_blocked |
Connect این شناسهٔ نصب را مجاز نمیداند، یا بازنشسته شده است |
pins_changed |
یک Connect سفارشی شناسههای برنامهٔ متفاوتی اعلام کرد |
protocol |
Connect پاسخی داد که این سرور نمیفهمد |