התחברות חיצונית (SSO)

התחברות חיצונית (SSO) מאפשרת למשתמשים להתחבר להתקנת Nodaro דרך ספק זהות (IdP) מהימן. באינטגרציה העיקרית, ספק הזהות שלכם חותם על assertion קצר־מועד בפורמט JWT, Nodaro מאמת אותו, והדפדפן מקבל סשן Nodaro רגיל. SSO כבוי עד שמנהל השרת של ההתקנה מגדיר לפחות ספק אחד.

החשבון שהמשתמש מגיע אליו הוא חשבון רגיל. SSO לא מוסיף פרטי גישה מיוחדים: הוא רק דרך להתחיל סשן.

שתי דרכי אינטגרציה

הגדרת ספקים

הגדירו בשרת את EXTERNAL_SSO_PROVIDERS למערך JSON של ספקים, ישירות בתוך המשתנה או כ-@/path/to/providers.json (תו @ בהתחלה גורם לקריאת הקובץ שבנתיב הזה). ערך פגום עוצר את השרת באתחול, כך שטעות הקלדה לעולם לא תשמיט ספק בשקט ולא תשאיר את ההתחברות מוגדרת רק בחלקה.

[
  {
    "id": "acme-chat",
    "label": "Acme Chat",
    "kind": "assertion",
    "secret": "a-dedicated-32-character-hmac-key-for-nodaro-only",
    "audience": "nodaro",
    "claimMap": { "email": "email", "emailVerified": "email_verified", "subject": "sub" },
    "initiateUrl": "https://chat.example.com/oauth/nodaro",
    "maxLifetimeSeconds": 300
  },
  {
    "id": "keycloak",
    "label": "Acme (Keycloak)",
    "kind": "oidc",
    "supabaseProvider": "keycloak"
  }
]

• השדה initiateUrl לא מעביר שום דבר לספק הזהות. אם אתם רוצים שהמשתמש יגיע לדף מסוים אחרי ההתחברות, ספק הזהות שלכם מוסיף &next=<path> כשהוא מפנה אותו בחזרה.
• המפתחות של initiateUrlByHost נבדקים באתחול: מפתח עם אותיות גדולות או עם פורט עוצר את השרת. המיפוי לעולם לא מתפרסם, וקישור החשבונות לא מושפע מהמארח שדרכו המשתמש הגיע.

החוזה של ה-assertion

ספק הזהות שלכם מנפיק JWT ושולח את הדפדפן אל GET /v1/sso/:provider?assertion=<jwt>. Nodaro מקבל את ה-assertion רק כשכל הכללים מתקיימים:

• אלגוריתם. ה-JWT חתום עם HS256 ועם ה-secret של הספק.
• קהל יעד. ה-claim aud שווה ל-audience של הספק.
• תפוגה. ה-claim exp קיים והוא לא בעבר, עם סובלנות של 5 שניות להפרשי שעונים.
• אורך חיים. ההפרש exp פחות iat הוא לכל היותר maxLifetimeSeconds, לפי השעון של Nodaro. ערך iat שנמצא יותר מ-5 שניות בעתיד מוגבל לטווח המותר, ו-iat חסר נחשב לרגע הנוכחי.
• שימוש חד־פעמי. ה-claim jti קיים וייחודי. Nodaro זוכר כל jti עד שחלון התוקף של ה-assertion עצמו עובר, ודוחה אותו בפעם השנייה.
• אימייל. ה-claim של האימייל קיים.
• אימייל מאומת. כדי שחשבון ייווצר או יקושר, דגל האימות חייב להיות true. דגל חסר נחשב לאימייל לא מאומת.

כש-assertion נכשל, התגובה היא 401 עם invalid_signature, invalid_claims, expired, too_long_lived, missing_jti, missing_email או assertion_replayed. נקודת הקצה מקבלת עד 20 בקשות ב-60 שניות מכל כתובת IP; מעבר לזה היא מחזירה 429 rate_limit_exceeded עם כותרת Retry-After.

הדוגמה הזאת, מהצד של ספק הזהות, מנפיקה assertion תקף עם הספרייה jose ל-Node.js:

import { SignJWT } from "jose"
import { randomUUID } from "node:crypto"

const secret = new TextEncoder().encode(process.env.NODARO_SSO_SECRET)

const assertion = await new SignJWT({ email: user.email, email_verified: true })
  .setProtectedHeader({ alg: "HS256" })
  .setSubject(user.id)
  .setAudience("nodaro")
  .setIssuedAt()
  .setExpirationTime("2m")
  .setJti(randomUUID())
  .sign(secret)

const url = new URL("https://nodaro.example.com/v1/sso/acme-chat")
url.searchParams.set("assertion", assertion)
url.searchParams.set("next", "/projects")
res.redirect(url.toString())

זרימת ההתחברות

1. המשתמש לוחץ על כפתור ה-SSO בדף ההתחברות של Nodaro, והדף קורא ל-GET /v1/sso/:provider בלי assertion.
2. Nodaro מפנה (302) אל ה-initiateUrl של הספק.
3. ספק הזהות מאמת את המשתמש ושולח את הדפדפן בחזרה אל GET /v1/sso/:provider?assertion=<jwt>, ואפשר להוסיף גם &next=<path>.
4. Nodaro מאמת את ה-assertion, דוחה שימוש חוזר ומחיל את כללי קישור החשבונות.
5. Nodaro מפנה אל /sso?sso_token=<one-time token>. הדף הזה מחליף את האסימון החד־פעמי בסשן.
6. המשתמש מגיע אל /projects, או אל הנתיב שב-next.

ספק זהות, כגון מארח שמטמיע את Nodaro, יכול גם להתחיל בשלב 3: הוא מפנה את הדפדפן לנקודת הקצה של ההחלפה עם assertion חדש. הפרמטר ?redirect= של דף ההתחברות עצמו לא עובר דרך ההפניות של SSO; עובר רק next שספק הזהות הוסיף.

הצגת כפתור ה-SSO בדף ההתחברות

דף ההתחברות מציג כפתור SSO כששני התנאים מתקיימים:

• פרופיל הממשק של הפריסה כולל את sso ב-auth.methods ומגדיר את auth.ssoLabel. פרופיל בלי ssoLabel מסיר את sso מהשיטות. הטקסט של הכפתור הוא ה-ssoLabel.
• מוגדר לפחות ספק אחד. הדף בודק את GET /v1/sso/providers.

פרופילי ממשק זמינים במהדורות Business ו-Cloud. ראו את הדף מהדורות ופרופילי ממשק.

פרופיל שה-auth.methods שלו כולל רק את sso מפעיל גם מחסום בצד השרת. כל חשבון מחובר חייב להיות חשבון שנוצר או קושר דרך SSO, וכל סשן אחר נדחה בקריאת ה-API הראשונה שלו עם 403 sso_required. החריג היחיד הוא חשבון החיוב של הפריסה, שמתואר בהמשך. הוספת email לשיטות מכבה את המחסום בכל ההתקנה.

איך חשבונות מקושרים

כש-assertion תקף, Nodaro מוצא את החשבון או יוצר אותו לפי כללים שנבנו כך ש-assertion לעולם לא יכול להשתלט על חשבון קיים רק כי יש לו אותה כתובת אימייל.

המשתנה EXTERNAL_SSO_LINK_EXISTING כבוי כברירת מחדל, וזו ההגדרה שמגינה מפני השתלטות. רק הערכים true או 1, בלי הבדל בין אותיות גדולות לקטנות, מפעילים אותו. הפעילו אותו רק כשאתם בוטחים ב-claims של אימייל מאומת שמגיעים מספקי הזהות שלכם, עד כדי כך שאתם מוכנים לקשר אותם לחשבונות שכבר קיימים.

הדחיות account_exists ו-email_unverified מנוסחות באותו אופן לכל חשבון, כך שאי אפשר להשתמש בטופס ההתחברות כדי לגלות לאיזו כתובת יש תפקיד מיוחד. התגובה היא account_exists גם כשהכתובת תואמת יותר מחשבון אחד, כשהחיפוש נכשל וכששתי התחברויות מתחרות על יצירת אותו חשבון.

בפריסה עם חשבון חיוב

פריסה יכולה להגדיר חשבון חיוב אחד שמשלם על כל המשתמשים של ההתקנה; ראו את הדף ארנקים חיצוניים. הכללים לחשבון הזה מחמירים יותר, כי בו נמצאים הקרדיטים של הפריסה:

• הוא מקושר בהתחברות המאומתת הראשונה שלו, בלי קשר לערך של EXTERNAL_SSO_LINK_EXISTING. assertion לא מאומת עבורו נדחה עם email_unverified, ו-assertion מספק אחר נדחה עם account_linked_other_provider.
• כל התחברות מאוחרת יותר נבדקת שוב. האימייל חייב להיות מאומת, וה-subject חייב להיות זה שקישר את החשבון בפעם הראשונה. אחרת ההתחברות נדחית עם 403 account_linked_other_subject.
• הוא שומר סיסמה כגישת חירום, ליום שבו ספק הזהות לא יכול להנפיק עבורו assertion. בפריסה שמאפשרת רק SSO, טופס הסיסמה נמצא ב-/login?billing=1, ורק חשבון החיוב יכול להתחבר דרכו.
• מנהל של ההתקנה לא יכול לחסום או למחוק אותו (403 payer_account_protected), כך שתפקיד מנהל שספק הזהות של הפריסה עצמה מחלק לא יכול למנוע מההתקנה גישה לקרדיטים שלה.

אם ה-subject שספק הזהות נותן לחשבון החיוב משתנה אי פעם, ההתחברות של החשבון דרך SSO ממשיכה להיכשל עם account_linked_other_subject. החשבון עדיין יכול להתחבר עם הסיסמה שלו.

בפריסה עם חשבון חיוב, הכתובות של מנהלי הפלטפורמה (PLATFORM_OPERATOR_EMAILS, או PLATFORM_OWNER_EMAIL כשהמשתנה הראשון ריק) לעולם לא מקבלות קישור חדש. הן נדחות עם account_exists, וכך החשבונות של מנהלי הפלטפורמה נשארים מחוץ ל-SSO. חשבון של מנהל פלטפורמה שכבר מקושר ממשיך להתחבר.

ספקי OIDC ו-SAML

הסוגים oidc ו-saml מעבירים את ההתחברות ל-Supabase Auth של ההתקנה עצמה, שמאמת את התשובה של ספק הזהות. לשניהם יש מגבלות:

• oidc: דף ההתחברות מעביר את ה-id של הספק כשם של ספק ה-OAuth. לכן ה-id חייב להיות בעצמו השם של ספק OAuth שמוגדר ב-Supabase Auth של ההתקנה, כגון keycloak או azure.
• saml: דף ההתחברות מעביר את ה-id של הספק כדומיין ה-SAML. ה-id לא יכול להכיל נקודה, ולכן אי אפשר לבטא דומיין כגון acme.com, וספק מסוג saml לא עובד מקצה לקצה.
• assertion שנשלח לספק מסוג oidc או saml נדחה עם 400 not_assertion_provider.

נקודות קצה

שתי נקודות הקצה ציבוריות ולא דורשות אסימון. אלה הנתיבים היחידים תחת /v1/sso/.

הערות אבטחה

• השתמשו בסוד ייעודי. ה-secret הוא מפתח אימות של Nodaro בלבד, נפרד מסוד הסשנים של ספק הזהות עצמו.
• כל assertion עובד פעם אחת. בדיקת ה-jti דוחה assertion שנשלח בפעם השנייה, ומגבלת אורך החיים שומרת על חלון זמן קצר.
• ההפניות נשארות בתוך ההתקנה. Nodaro מקבל את next רק כנתיב יחסי באותה התקנה, שמתחיל ב-/ אבל לא ב-//. כל ערך אחר מוביל אל /projects.
• שום סוד לא יוצא מהשרת. הנתיב GET /v1/sso/providers מחזיר רק id, label ו-kind. ה-assertion והאסימון החד־פעמי מושמטים מיומני הבקשות.
• על ההחלפה חלה מגבלת קצב לכל כתובת IP.