انتقل إلى المحتوى الرئيسي

المؤسسات والأشخاص والتفويضات

لا يستطيع الشخص أن يفعل شيئًا في OktoID إلا لأنه يحمل تفويضًا: حزمة من الصلاحيات، لـمؤسسة واحدة وكل ما تحتها. ولا شيء مما يقوله مزوّد الهوية عن الشخص (مجموعة، أو دور، أو سمة) يمنحه أي سلطة. فتسجيل الدخول يُثبت مَن هو الشخص، وتفويضاته هي التي تقرّر ما يحق له فعله.

تشرح هذه الصفحة الأجزاء والقواعد التي تربط بينها. أما الطلبات التي تضعها موضع العمل، من بيئة تشغيل جديدة إلى مسؤول ثانٍ يسجّل الدخول، فهي في التثبيت وتسجيل الدخول.

المؤسسات​

تشكّل المؤسسات شجرة. لكل مؤسسة مسار يتألف من الأسماء المختصرة التي فوقها، مثل /oktoid/acme/branch، ومعرّف (UUID) لا يتغير أبدًا.

  • أعلى الشجرة هو مؤسسة الارتكاز الجذرية. ينشئها تشغيل الإعداد من ملف الإجابات الخاص بالنشر، وهي في بيئة التشغيل المحلية /oktoid.
  • تُنشأ المؤسسة بالطلب POST /api/v1/subjects، تحت المؤسسة التي تتصرّف نيابةً عنها، أو تحت parentPath داخلها.
  • الاسم المختصر أحرف لاتينية صغيرة وأرقام وشَرطات، طوله من 1 إلى 63 حرفًا، يبدأ بحرف أو رقم وينتهي بحرف أو رقم. وهو فريد بين المؤسسات الواقعة تحت الأم نفسها.

المؤسسات المذكورة في ملف الإجابات ينشئها تشغيل الإعداد عند كل نشر إن لم تكن موجودة.

الأشخاص​

الشخص هو مَن يسجّل الدخول. يُسجَّل بالطلب POST /api/v1/persons، ويقع تحت المؤسسة التي سجّلته: الشخص المسجَّل لمؤسسة acme مساره /oktoid/acme/<their id>.

  • الشخص طرفٌ أخير في الشجرة دائمًا. لا يمكن إنشاء أي شيء تحت شخص.
  • ينتهي مسار الشخص بمعرّفه، لا باسمه أبدًا. تظهر المسارات في سجلات التشغيل وسجلات التدقيق، ولو ظهر فيها الاسم لكان بيانات شخصية في أماكن لا تُمحى أبدًا.
  • الأسماء وعنوان البريد الإلكتروني بيانات شخصية. تُخزَّن مشفّرةً بمفتاح يخص ذلك الشخص وحده، ولا تُكتب في سجلات التشغيل أبدًا، وتختفي من كل رد بمجرد محو الشخص. ومحو الشخص يُتلف ذلك المفتاح، فتصبح القيم المخزّنة غير قابلة للقراءة. لا يوجد في هذا الإصدار طلب يمحو شخصًا.
  • "invite": true ينشئ حساب الشخص في نطاق الموظفين لدى مزوّد الهوية، ويرسل إليه دعوة. وقبل أن يتمكن الحساب من تسجيل الدخول، يجب على صاحبه أن يتحقق من عنوان البريد الإلكتروني، ويعيّن كلمة المرور، ويُعِدّ عامل التحقق الثاني بتطبيق مصادقة. ودون invite، يكون الشخص موجودًا في OktoID لكن ليس له حساب يسجّل به الدخول.

تسجيل شخص لا يمنحه أي سلطة. وإلى أن يمنحه أحدٌ تفويضًا بحزمة، يستطيع أن يسجّل الدخول ولا يستطيع أن يفعل شيئًا.

الحزم​

الحزمة مجموعة صلاحيات لها اسم. في هذا الإصدار حزمتان، ينشئهما تشغيل الإعداد. ولا يوجد طلب ينشئ حزمة أو يغيّرها.

الحزمةما تضمّهمَن يحملها
ENTITY_ADMINكل صلاحية يعرّفها هذا الإصدار: إنشاء المؤسسات وقراءتها، وإنشاء الأشخاص وقراءتهم، وإنشاء التفويضات وقراءتها وسحبهامسؤولو المؤسسة، والحساب الجذري على مؤسسة الارتكاز الجذرية
ORGANIZATION_CLIENTإنشاء المؤسسات وقراءتهاالعملاء الآليون، ما لم يذكر ملف الإجابات حزمة أخرى لأحدهم

تعريفات الصلاحيات في @oktoid/contracts هي المرجع فيما تضمّه كل حزمة.

التفويضات​

يقول التفويض: هذا الشخص يحمل هذه الحزمة لـهذه المؤسسة. وهو يمنح صلاحيات الحزمة على المؤسسة وكل ما تحتها، ولا شيء فوقها أو بجانبها.

  • يُمنح التفويض بالطلب POST /api/v1/grants، مع ذكر الشخص (granteeId) والمؤسسة (organizationId) والحزمة.
  • لا يحمل الشخص أكثر من تفويض نشط واحد لكل مؤسسة. ولتغيير الحزمة، اسحب التفويض وامنح تفويضًا جديدًا.
  • يجوز للشخص أن يحمل تفويضات لعدة مؤسسات، ويتصرّف نيابةً عن واحدة منها في كل مرة.
  • يسرد GET /api/v1/grants تفويضات المؤسسات الواقعة داخل مؤسستك، مع التصفية بحسب organization أو grantee أو status.
  • يُدوَّن كل تفويض وكل سحب للتفويض في سجل التدقيق، مع مَن قام به.

التفويض يمنح سلطةً، لا رؤيةً لما سواه. كل ما هو خارج المؤسسة التي تتصرّف نيابةً عنها يجيب بـ 404، تمامًا كما يجيب شيء غير موجود. والرفض لا يخبرك أبدًا بما إذا كان الشيء موجودًا.

العملاء الآليون يحملون تفويضات أيضًا: تفويضًا واحدًا لكل منهم، للمؤسسة التي يذكر ملف الإجابات أنه يتصرّف نيابةً عنها، ويمنحه تشغيل الإعداد. أما التفويض الممنوح عبر الواجهة فهو دائمًا لشخص.

الإنابة لا تزيد الصلاحيات أبدًا، بل تقلّصها​

لا تستطيع أن تمنح إلا ما تحمله أنت، وداخل مؤسستك فقط. ويُرفض التفويض ما لم يتحقق الشرطان:

  • أن تكون كل صلاحية في الحزمة صلاحيةً يتضمنها تفويضك أنت، و
  • أن تكون المؤسسة هي التي تتصرّف نيابةً عنها، أو واقعةً تحتها.

فمسؤول /oktoid/acme يستطيع أن يعيّن مسؤولًا آخر لـ /oktoid/acme أو لـ /oktoid/acme/branch، لكن ليس لـ /oktoid، ولا يستطيع أن يمنح حزمة أكبر من حزمته. والتفويض المرفوض يجيب بـ 404، وهو الجواب نفسه الذي يُعطى لمؤسسة أو شخص غير موجود.

وتنطبق القاعدة نفسها على السحب: لا تستطيع أن تسحب تفويضًا أكبر من تفويضك، فلا يستطيع مسؤولٌ أضيق صلاحيةً أن يُقصي مسؤولًا أوسع منه.

التصرّف نيابةً عن مؤسسة​

كل طلب يقدّمه شخص يذكر المؤسسة التي يتصرّف نيابةً عنها، في الترويسة

Oktoid-Acting-For: <the organization's id>

في ذلك الطلب، يقتصر وصول الشخص على تلك المؤسسة وفروعها التابعة، وتكون صلاحياته صلاحيات الحزمة التي في تفويضه هناك.

  • دون الترويسة، يُرفض طلب الشخص بـ 403.
  • مع مؤسسة لا يحمل تفويضًا لها، يُرفض الطلب بـ 403 نفسها، سواء كانت المؤسسة موجودة أم لا.
  • العملاء الآليون لا يرسلون الترويسة. فهم يتصرّفون نيابةً عن المؤسسة الوحيدة التي يذكرها تفويضهم.

لتعرف المؤسسات التي تستطيع التصرّف نيابةً عنها، اسأل GET /api/v1/me. فهو الطلب الوحيد الذي لا يتصرّف نيابةً عن أي مؤسسة: لا يأخذ الترويسة Oktoid-Acting-For، ويتجاهلها إن أُرسلت، ولا يحتاج إلى أي صلاحية. ويجيب بتفويضاتك النشطة، ومع كل منها معرّف المؤسسة (القيمة التي توضع في الترويسة)، ومسارها، والحزمة:

{"grants":[{"organizationId":"<a UUID>","path":"/oktoid/acme","bundle":"ENTITY_ADMIN"}]}

ولا يُظهر أبدًا تفويضات أي شخص آخر. وإن لم تكن تحمل أي تفويض، تكون القائمة فارغة، لا خطأً. وهو يقرأ تفويضاتك من جديد عند كل استدعاء، فيظهر فيه فورًا كل تفويض مُنح أو سُحب، حتى في الوقت الذي لا يزال فيه تفويض مسحوب يُجيز الطلبات (انظر سحب التفويض). وفي بيئة التشغيل المحلية، يطبع pnpm oktoid login القائمة نفسها عند تسجيل دخولك (التثبيت وتسجيل الدخول، الخطوة 5).

سحب التفويض​

POST /api/v1/grants/{id}/revoke

تصبح حالة التفويض revoked، ويُدوَّن التغيير في سجل التدقيق. وسحب تفويض مسحوب من قبل يجيب بالتفويض المسحوب نفسه ولا يغيّر شيئًا.

يسري سحب التفويض في غضون عمر رمز وصول واحد: خمس دقائق على الأكثر. تتذكّر البوابة ما يحق للشخص الذي سجّل الدخول فعله لمدة قصيرة، لا تزيد أبدًا على خمس دقائق ولا تتجاوز أبدًا انتهاء صلاحية رمز الوصول الذي يحمله. وإلى أن تنتهي تلك الذاكرة، يمكن لتفويض مسحوب أن يُجيز الطلبات. فخذ هذه المدة في الحسبان حين تزيل وصول شخص على عجل: اسحب التفويض، وتوقّع أن يبقى له وصول لمدة تصل إلى خمس دقائق.

مَن يستطيع أن يسحب تفويض مَن​

يحتاج سحب التفويض إلى الأمور الثلاثة نفسها التي يحتاجها منحه: صلاحية سحب التفويض (لا تضمّها في هذا الإصدار إلا ENTITY_ADMIN)، وأن يكون التفويض لمؤسسة هي التي تتصرّف نيابةً عنها أو واقعة تحتها، وأن تكون حزمته غير أكبر من حزمتك. ولا يُنظر إلى مَن منح التفويض. وعمليًا:

  • كل من يحمل صلاحية سحب التفويض يستطيع أن يسحب تفويضه هو. ويشمل ذلك آخر مسؤول في مؤسسة، فيتركها بلا مسؤول. والحساب الجذري هو الاستثناء من حيث الأثر: يستعيد تشغيل الإعداد التالي تفويضه (انظر الحساب الجذري).
  • يستطيع المسؤول النظير أن يسحب تفويض المسؤول الذي عيّنه. فإذا عيّن مسؤولُ /oktoid/acme مسؤولًا ثانيًا لـ /oktoid/acme، استطاع كلٌّ منهما أن يسحب تفويض الآخر.
  • لا يستطيع المسؤول أن يسحب تفويضًا فوق مؤسسته. فمسؤول /oktoid/acme الذي عيّنه الحساب الجذري لا يستطيع أن يسحب تفويض الحساب الجذري على /oktoid.

سحب التفويض لا يسحب التفويضات التي مُنحت به​

عندما يسحب شخصٌ تفويضًا، تبقى التفويضات التي منحها حامله نشطة. فإذا عيّن مسؤولُ /oktoid/acme آخرين ثم سُحب تفويضه، يبقى كل تفويض منحه ساريًا. ويذكر كل تفويض مَن منحه (grantedBy في رد GET /api/v1/grants)، وكل تفويض وكل سحب للتفويض مدوَّن في سجل التدقيق مع مَن قام به، لذا يمكن العثور على التفويضات التي منحها مسؤول أُزيل، وسحبها واحدًا تلو الآخر.

أما سحب التفويض الذي تُجريه المنصة نفسها، لا شخص، فيمتد إلى ما تحته. إذ يسحب أيضًا التفويضات التي مُنحت بالتفويض المسحوب. وحالة السحب الوحيدة من هذا النوع في هذا الإصدار هي سحب تشغيل الإعداد، عندما يعطي ملف الإجابات عميلًا آليًا حزمة مختلفة: يُسحب تفويضه القديم ويُمنح تفويض جديد، ويُدوَّن الأمران في سجل التدقيق.

الحساب الجذري​

الحساب الجذري هو أول حساب موظف، ينشئه تشغيل الإعداد لصندوق البريد الذي يذكره ملف الإجابات. وهو يحمل ENTITY_ADMIN على مؤسسة الارتكاز الجذرية، ومنه ينحدر كل تفويض آخر.

يستعيد تشغيل الإعداد تفويض الحساب الجذري. فإذا سُحب التفويض أو فُقد، أعاد تشغيل الإعداد التالي منحه. وفي بيئة التشغيل المحلية، يكون ذلك عند pnpm stack:up التالي. ثم يقوم تشغيل الإعداد بما يلي:

  • يدوّن التفويض الجديد في سجل التدقيق، كأي تفويض؛
  • يُبلغ عن ملاحظة root-grant-restored في ناتجه.

لذا فإن سحب تفويض الحساب الجذري ليس طريقة لإزالة الحساب الجذري. ولمنع استخدام حساب جذري مُخترَق، غيّر بيانات الدخول الخاصة به لدى مزوّد الهوية.