OAuth2 / OIDC — חיבור שירות ל-Omniscol
Premiumדף זה מיועד להנהלת מערכות המידע. הוא מתאר את Omniscol בתפקידו כשרת הרשאות OAuth2 / OpenID Connect: כיצד שירות צד שלישי נרשם כלקוח, כיצד משתמש מסכים להעניק לו גישה, וכיצד השירות מקבל טוקן המוגבל ל-scopes שהוענקו.
מה Omniscol עושה כשרת OAuth2
שירות חיצוני — סוכן AI, מחבר, לוח מחוונים — הופך ללקוח שהוצהר בחשבון שלכם; משתמש בבית הספר מאשר את הגישה שלו במסך הסכמה; השירות מקבל אז טוקן גישה קצר מועד, שהיקפו מוגבל ל-scopes שהוענקו ולהרשאות המשתמש.
מנגנון זה שונה מ-SSO של משתמשים המתואר בדף OIDC / SSO, שבו Omniscol הוא להפך לקוח של ספק הזהויות שלכם כדי לחבר את המשתמשים שלכם. כאן Omniscol נמצא בצד השרת: שירותים הם שמתחברים אליו.
שני שילובים של Omniscol משתמשים בשרת הזה:
- MCP — ההזדהות הרגילה של סוכן AI עוברת דרך שרת ה-OAuth2 הזה (ראו MCP — חיבור סוכן AI חיצוני);
- OneRoster — יצרן OneRoster מזדהה באמצעות טוקן OAuth2 ממכונה למכונה שמונפק בידי אותו שרת (ראו OneRoster).
כל שירות אחר התואם ל-OAuth2 / OIDC יכול להתחבר אליו באותו האופן.
גילוי ונקודות הקצה של הפרוטוקול
Omniscol מפרסם את מטא-נתוני הגילוי שלו בכתובות
.well-known הסטנדרטיות, המוגשות בשורש הדומיין של החשבון שלכם (למשל
https://votre-ecole.omniscol.com). לקוח תואם מוצא שם בעצמו את כל
נקודות הקצה, בלי תצורה ידנית:
/.well-known/oauth-authorization-server— מטא-נתוני שרת ההרשאות (RFC 8414);/.well-known/openid-configuration— מטא-נתוני OpenID Connect (תוכן זהה לקודם);/.well-known/jwks.json— מפתחות ציבוריים לאימות (JWKS), המאפשרים לאמת את חתימת ה-id_token;/.well-known/oauth-protected-resource— מטא-נתוני משאב מוגן (RFC 9728).
מטא-נתונים אלה מכריזים על נקודות הקצה של הפרוטוקול:
/oauth/authorize— בקשת הרשאה (מסך התחברות ואחריו מסך הסכמה);/oauth/token— המרת הקוד לטוקן, וחידוש;/oauth/register— רישום דינמי של לקוחות (RFC 7591);/oidc/userinfo— מידע על המשתמש המחובר (OIDC);/oauth/revoke— ביטול טוקן (RFC 7009).
נקודות הקצה של הפרוטוקול הן ציבוריות: הן אינן שמורות לחשבונות Premium ואין צורך לפתוח אותן ידנית. רק מסך ניהול הלקוחות המתואר בהמשך שייך ל-Premium.
זרמי ההרשאה
Omniscol תומך בשלושה זרמי OAuth2:
- קוד הרשאה עם PKCE — זרם ברירת המחדל לשירות
הפועל בשם משתמש. השירות מפנה את המשתמש
אל
/oauth/authorize; לאחר התחברות והסכמה, Omniscol מחזיר קוד הרשאה (בתוקף 5 דקות) שהשירות ממיר ב-/oauth/token. שיטת ה-PKCE שנבחרה היא S256, וה-response_typeהיחיד המתקבל הואcode. - חידוש (
refresh_token) — להארכת גישה מואצלת בלי לעבור שוב את ההסכמה. - Client credentials — זרם ממכונה למכונה, בלי משתמש, המשמש בעיקר צרכני OneRoster. הלקוח מזדהה ישירות ומקבל טוקן גישה.
בהמרה, השרת מנפיק טוקן גישה (Bearer, בתוקף
שעה אחת) ולזרמי משתמש גם טוקן חידוש
(בתוקף 30 יום). כאשר מתבקש ה-scope openid, מונפק גם
id_token חתום של OIDC; את חתימתו מאמתים דרך
/.well-known/jwks.json. הזרם client_credentials מנפיק רק טוקן
גישה, בלי חידוש ובלי id_token.
טוקן הגישה מוצג לאחר מכן בכותרת ה-HTTP
Authorization: Bearer <טוקן>. בכל קריאה, Omniscol בודק את
חתימתו, מוודא שהלקוח עדיין בסטטוס פעיל, שהמשתמש
עדיין קיים ובעל התפקיד הנדרש, ושה-scopes של הטוקן
מכסים אכן את נקודת הקצה הנקראת — אחרת הקריאה נדחית.
ה-scopes וההסכמה
ה-scopes שאתם מנהלים בלקוח הם:
read:basic— קריאת מערכות שעות, לוחות מחוונים ועיונים (המודולים דף הבית, מערכת שעות, לוח מחוונים, ניהול מערכות שעות);read:user— קריאת רשימת המשתמשים;write:data— כתיבה באותם מודולי עיון;admin— גישת ניהול (המודולים ניהול, ניהול היעדרויות, ניהול מערכות שעות).
השרת מכיר גם את ה-scopes של OIDC (openid, email, profile) ואת
ה-scopes של OneRoster לקריאה בלבד (הקידומת imsglobal.org). אלה
האחרונים בעלי הרשאה מוגברת: לקוח אינו יכול להעניק אותם
לעצמו באמצעות הרישום הדינמי; יש להגדיר אותם בידי
מנהל מערכת בכרטיס הלקוח.
ה-scope שמוענק בפועל הוא החיתוך בין מה שהלקוח
מבקש לבין מה שרשום עבורו: לקוח אינו מקבל לעולם יותר
ממה שמופיע בכרטיס שלו. בזרם המשתמש, מסך
ההסכמה (/oauth/consent) מציג את השם ואת הלוגו של השירות
המבקש וכן את הרשימה הקריאה של ה-scopes המבוקשים, עם
הכפתורים קבל ו-סרב. אישור מנפיק את קוד
ההרשאה ומחזיר את המשתמש אל השירות; סירוב מחזיר אותו
עם השגיאה access_denied.
הרישום הדינמי של לקוחות
נקודת הקצה /oauth/register מממשת את הרישום
הדינמי (Dynamic Client Registration, RFC 7591): שירות תואם יכול
להצהיר על עצמו כלקוח, בלי התערבות ידנית מראש. זה
מה שמאפשר לסוכן MCP להגדיר את עצמו מכתובת
השרת בלבד.
הרישום הדינמי אינו יכול להעניק לעצמו scope בעל הרשאה מוגברת
(ה-scopes של OneRoster): אלה נדחים בשקט, ואם לא נותר אף
scope תקף, מוענק כברירת מחדל read:basic. ה-scopes
בעלי ההרשאה המוגברת נשארים שמורים להגדרה בידי מנהל מערכת.
מסך ניהול לקוחות OAuth2
בחשבונות פרימיום, מנהלים את הלקוחות מתוך ניהול → ייבוא/ייצוא, בקטע OAuth2, באמצעות הכפתור OAuth2. הגישה דורשת תחילה את סיסמת מנהל המערכת — אישור נוסף לפני פתיחת המסך.
המסך מציג את הלקוחות הרשומים ולכל אחד מהם את מצבו (פעיל / לא פעיל), שמו, ה-scopes שלו, אנשי הקשר שלו וה-URIs שלו (אתר אינטרנט, לוגו, URIs להפניה). ניתן:
- לרשום לקוח — הזינו את השם,
software_idלא חובה, את ה-scopes, אנשי הקשר, אתר האינטרנט, הלוגו וה-URIs להפניה. בעת היצירה, Omniscol מציג פעם אחת בלבד את ה-client_idואת ה-client_secret. - לשנות לקוח — ניתן לשנות רק שדות בטוחים: שם,
scopes, אנשי קשר, אתר אינטרנט ולוגו. את ה-URIs להפניה, את ה-
software_idואת הסוד אי אפשר לשנות כאן. - להפעיל או להשבית לקוח — הטוקנים של לקוח שהושבת נדחים כבר בקריאה הבאה.
- למחוק לקוח — המחיקה סופית.
סוד הלקוח
ה-client_secret מוצג פעם אחת בלבד, בעת הרישום.
Omniscol שומר אצלו רק גיבוב (hash) של הסוד, לעולם לא את
הסוד בטקסט גלוי: אי אפשר להציג אותו שוב או לשחזר אותו לאחר מכן.
העתיקו אותו מיד למנהל סודות.
ה-client_id, לעומת זאת, דטרמיניסטי: הוא נגזר משם החשבון, משם
הלקוח ומגיבוב של המטא-נתונים הטכניים שלו. שני
רישומים זהים לחלוטין מגיעים אפוא לאותו
מזהה.
חידוש הסוד (רוטציה)
רוטציה של הסוד קיימת: היא מנפיקה סוד חדש, שומרת
רק את הגיבוב החדש, ומחזירה את הסוד החדש פעם אחת בלבד.
היא מתבצעת דרך נקודת הקצה לניהול הרישום הדינמי
(/oauth/register/<client_id>/rotation) ומחייבת להציג את טוקן
הרישום שנמסר ללקוח בעת הרישום הדינמי שלו. היא
אינה מופעלת אפוא ממסך הניהול שלמעלה, שאינו
מטפל בטוקן זה.
OAuth2 או מפתח API: במה לבחור
Omniscol מציע שני מנגנוני גישה למכונות, בעלי מודלי אמון שונים:
- OAuth2 (דף זה) — צד שלישי רשום מקבל, לאחר
הסכמה של משתמש, טוקן קצר מועד (שעה), מוגבל
ל-scopes שהוענקו, ניתן לחידוש וניתן לביטול (על ידי
השבתת הלקוח). הזרם
client_credentialsמכסה בנוסף ממכונה למכונה בלי משתמש. זהו המצב המתאים לשירות צד שלישי מזוהה, ל-MCP ול-OneRoster. - מפתח API (ראו Omniscol API) — טוקן עצמאי חתום בידי השרת, הנושא רשימת נקודות קצה מותרות ושאתם מוסרים בעצמכם למערכת החיצונית: בלי צד שלישי רשום, בלי מסך הסכמה, בלי חידוש. זוהי האצלה בידי מנהל המערכת של הרשאותיו שלו למערכת שבשליטתו.
בקיצור: מפתח API מתאים כשאתם מוסרים בעצמכם גישה למערכת שבשליטתכם; OAuth2 מתאים כששירות צד שלישי מזוהה צריך לקבל גישה מואצלת, מוגבלת בהיקף וניתנת לביטול, או כשהפרוטוקול מחייב זאת (MCP, OneRoster).
מדריך
רישום לקוח OAuth2
-
פתחו את מסך OAuth2. ב-ניהול → ייבוא/ייצוא, בקטע OAuth2, לחצו על הכפתור OAuth2, ואז הזינו את סיסמת מנהל המערכת.
-
רשמו את הלקוח. הזינו את שמו, את ה-scopes שלו (
read:basic,read:user,write:data,admin), את ה-URIs להפניה שלו ואם צריך אנשי קשר, אתר אינטרנט ולוגו. את ה-scopes של OneRoster אי אפשר להעניק כאן באמצעות הרישום הדינמי; הם מוגדרים בידי מנהל מערכת. -
העתיקו את ה-
client_idואת ה-client_secretשמוצגים. הסוד מופיע פעם אחת בלבד: שמרו אותו במנהל סודות. -
בצד השירות, הגדירו את הלקוח עם הפרטים האלה ועם כתובת השרת; לקוח תואם מגלה בעצמו את נקודות הקצה דרך
/.well-known/. -
כדי לבטל גישה, חזרו למסך והשביתו או מחקו את הלקוח.