> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/on-premises/ar/aliadadat/overleaf-toolkit/authentication/saml-authentication.md).
# مصادقة SAML
هذه الميزة مطوَّرة بواسطة [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). هنا نقدّم بعض المستندات لتكوينك.
### الإعدادات
داخليًا، تستخدم وحدة Overleaf SAML [passport-saml](https://github.com/node-saml/passport-saml) المكتبة، ويتم تمرير معظم خيارات التكوين التالية إلى `passport-saml`. إذا كنت تواجه مشاكل في تهيئة SAML، فمن المفيد قراءة ملف README الخاص بـ `passport-saml` للاطلاع على شكل التهيئة التي يتوقعها.
متغير البيئة `EXTERNAL_AUTH` مطلوب لتمكين وحدة المصادقة SAML. يحدد متغير البيئة هذا طرق المصادقة الخارجية التي يتم تنشيطها. قيمة هذا المتغير هي قائمة. إذا تضمنت القائمة `saml` فسيتم تفعيل مصادقة SAML.
على سبيل المثال: `EXTERNAL_AUTH=ldap saml`
عند استخدام طريقة المصادقة SAML، تتم إعادة توجيه المستخدم إلى موقع المصادقة الخاص بموفر الهوية (IdP). إذا نجح موفر الهوية في مصادقة المستخدم، فسيتم التحقق من قاعدة بيانات مستخدمي Overleaf بحثًا عن سجل يحتوي على `samlIdentifiers` حقلًا مُنظَّمًا على النحو التالي:
```json
samlIdentifiers: [
{
externalUserId: "...",
providerId: "1",
userIdAttribute: "..."
}
]
```
إن `externalUserId` يجب أن يطابق قيمة الخاصية المحددة بواسطة `userIdAttribute` في ملف تعريف المستخدم الذي يعيده خادم IdP.
إذا لم يتم العثور على سجل مطابق، يتم البحث في قاعدة البيانات عن مستخدم يطابق عنوان بريده الإلكتروني الأساسي البريد الإلكتروني الموجود في ملف المستخدم الشخصي لدى IdP:
* إذا تم العثور على مثل هذا المستخدم، يتم `hashedPassword` يتم حذف الحقل لتعطيل المصادقة المحلية، و `samlIdentifiers` يتم إضافة الحقل.
* إذا لم يتم العثور على مستخدم مطابق، يتم إنشاء مستخدم جديد بعنوان البريد الإلكتروني و `samlIdentifiers` من الملف الشخصي لدى IdP.
**ملاحظة:** حاليًا، يتم دعم موفر هوية SAML واحد فقط. إن `providerId` الحقل في `samlIdentifiers` ثابت على `'1'`.
#### متغيرات البيئة
* `OVERLEAF_SAML_IDENTITY_SERVICE_NAME`
* اسم العرض لخدمة الهوية، ويُستخدم في صفحة تسجيل الدخول (الافتراضي: `تسجيل الدخول باستخدام موفر هوية SAML`).
* `OVERLEAF_SAML_USER_ID_FIELD`
* ستُستخدم قيمة هذه السمة من قِبل Overleaf كمعرّف مستخدم خارجي، والقيمة الافتراضية هي `nameID`.
* `OVERLEAF_SAML_EMAIL_FIELD`
* اسم حقل البريد الإلكتروني في ملف تعريف المستخدم، والقيمة الافتراضية هي `nameID`.
* `OVERLEAF_SAML_FIRST_NAME_FIELD`
* اسم حقل firstName في ملف تعريف المستخدم، والقيمة الافتراضية هي `givenName`.
* `OVERLEAF_SAML_LAST_NAME_FIELD`
* اسم حقل lastName في ملف تعريف المستخدم، والقيمة الافتراضية هي `lastName`
* `OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN`
* إذا تم ضبطه على `true`، يتم تحديث المستخدم `first_name` و `last_name` الحقل عند تسجيل الدخول، وإيقاف نموذج تفاصيل المستخدم في `/user/settings` الصفحة.
* `OVERLEAF_SAML_ENTRYPOINT` **(مطلوب)**
* عنوان URL لنقطة الدخول لخدمة هوية SAML.
* مثال: `https://idp.example.com/simplesaml/saml2/idp/SSOService.php`
* مثال Azure: `https://login.microsoftonline.com/8b26b46a-6dd3-45c7-a104-f883f4db1f6b/saml2`
* `OVERLEAF_SAML_ISSUER` **(مطلوب)**
* اسم المُصدِر.
* `OVERLEAF_SAML_AUDIENCE`
* الجمهور المتوقع لاستجابة SAML، والقيمة الافتراضية هي قيمة `OVERLEAF_SAML_ISSUER`.
* `OVERLEAF_SAML_IDP_CERT` **(مطلوب)**
* مسار إلى ملف يحتوي على الشهادة العامة لموفر الهوية، وتُستخدم للتحقق من توقيعات استجابات SAML الواردة. إذا كان لدى موفر الهوية عدة شهادات توقيع صالحة، فيمكن أن تكون مصفوفة JSON من المسارات إلى الشهادات.
* مثال (شهادة واحدة): `/var/lib/overleaf/certs/idp_cert.pem`
* مثال (شهادات متعددة): `["var/lib/overleaf/certs/idp_cert.pem", "/var/lib/overleaf/certs/idp_cert_old.pem"]`
* `OVERLEAF_SAML_PUBLIC_CERT`
* مسار إلى ملف يحتوي على شهادة توقيع عامة تُستخدم لتضمينها في طلبات المصادقة حتى يتمكن موفر الهوية من التحقق من توقيعات طلب SAML الوارد. وهو مطلوب عند إعداد [نقطة نهاية البيانات الوصفية](https://github.com/yu-i-i/overleaf-cep/wiki/Extended-CE:-SAML-Authentication#metadata-for-the-identity-provider) عندما يتم تهيئة الاستراتيجية باستخدام `OVERLEAF_SAML_PRIVATE_KEY`. يمكن توفير مصفوفة JSON من مسارات الشهادات لدعم تدوير الشهادات. عند تقديم مصفوفة من الشهادات، يجب أن يطابق الإدخال الأول في المصفوفة الشهادة الحالية `OVERLEAF_SAML_PRIVATE_KEY`. يمكن استخدام الإدخالات الإضافية في المصفوفة لنشر الشهادات القادمة إلى موفري الهوية قبل تغيير `OVERLEAF_SAML_PRIVATE_KEY`.
* `OVERLEAF_SAML_PRIVATE_KEY`
* مسار إلى ملف يحتوي على مفتاح خاص بتنسيق PEM يطابق `OVERLEAF_SAML_PUBLIC_CERT` ويُستخدم لتوقيع طلبات المصادقة المرسلة بواسطة passport-saml.
* `OVERLEAF_SAML_DECRYPTION_CERT`
* مسار إلى ملف يحتوي على شهادة عامة، تُستخدم لـ [نقطة نهاية البيانات الوصفية](https://github.com/yu-i-i/overleaf-cep/wiki/Extended-CE:-SAML-Authentication#metadata-for-the-identity-provider).
* `OVERLEAF_SAML_DECRYPTION_PVK`
* مسار إلى ملف يحتوي على مفتاح خاص يطابق `OVERLEAF_SAML_DECRYPTION_CERT` والذي سيُستخدم لمحاولة فك تشفير أي تأكيدات مشفرة يتم استلامها.
* `OVERLEAF_SAML_SIGNATURE_ALGORITHM`
* يمكن اختياريًا ضبط خوارزمية التوقيع لتوقيع الطلبات، والقيم الصالحة هي 'sha1' (الافتراضي)، و'sha256' (مُفضّل)، و'sha512' (الأكثر أمانًا، تحقّق مما إذا كان موفر الهوية لديك يدعمه).
* `OVERLEAF_SAML_ADDITIONAL_PARAMS`
* قاموس JSON لمعلمات الاستعلام الإضافية لإضافتها إلى جميع الطلبات.
* `OVERLEAF_SAML_ADDITIONAL_AUTHORIZE_PARAMS`
* قاموس JSON لمعلمات الاستعلام الإضافية لإضافتها إلى طلبات 'authorize'.
* مثال: `{"some_key": "some_value"}`
* `OVERLEAF_SAML_IDENTIFIER_FORMAT`
* تنسيق اسم المعرّف المطلوب من موفر الهوية (الافتراضي: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`). إذا كنت تستخدم `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`، فتأكد من أن `OVERLEAF_SAML_EMAIL_FIELD` متغير البيئة مُعرّف. إذا كان `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` مطلوبًا، فيجب عليك أيضًا تعريف `OVERLEAF_SAML_ID_FIELD` متغير البيئة، والذي يمكن، على سبيل المثال، تعيينه إلى عنوان البريد الإلكتروني للمستخدم.
* `OVERLEAF_SAML_ACCEPTED_CLOCK_SKEW_MS`
* المدة الزمنية بالمللي ثانية للانحراف المقبول بين العميل والخادم عند التحقق من أختام صلاحية شروط التأكيد OnBefore وNotOnOrAfter. يؤدي الضبط على -1 إلى تعطيل التحقق من هذه الشروط بالكامل. القيمة الافتراضية هي 0.
* `OVERLEAF_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX`
* `AttributeConsumingServiceIndex` سمة تُضاف إلى AuthnRequest لإرشاد موفر الهوية إلى مجموعة السمات التي يجب إرفاقها بالاستجابة ([رابط](http://blog.aniljohn.com/2014/01/data-minimization-front-channel-saml-attribute-requests.html)).
* `OVERLEAF_SAML_AUTHN_CONTEXT`
* مصفوفة JSON من قيم تنسيق اسم المعرّف لطلب سياق المصادقة. الافتراضي: `["urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"]`.
* `OVERLEAF_SAML_FORCE_AUTHN`
* إذا `true`، يحدد طلب SAML الأولي من موفر الخدمة أن يقوم موفر الهوية بفرض إعادة مصادقة المستخدم، حتى إذا كان يمتلك جلسة صالحة.
* `OVERLEAF_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT`
* إذا `true`، لا تطلب سياق مصادقة محددًا. على سبيل المثال، يمكنك تعيين هذا إلى `true` للسماح بسياقات إضافية مثل عمليات تسجيل الدخول بدون كلمة مرور (`urn:oasis:names:tc:SAML:2.0:ac:classes:X509`). يعتمد دعم السياقات الإضافية على موفر الهوية لديك.
* `OVERLEAF_SAML_AUTHN_REQUEST_BINDING`
* إذا تم ضبطه على `HTTP-POST`، سيطلب المصادقة من موفر الهوية عبر ربط HTTP POST، وإلا فسيكون الافتراضي HTTP-Redirect.
* `OVERLEAF_SAML_VALIDATE_IN_RESPONSE_TO`
* إذا `always`، فسيتم التحقق من InResponseTo من استجابات SAML الواردة.
* إذا `أبدًا`، فلن يتم التحقق من InResponseTo (الافتراضي).
* إذا `ifPresent`، فسيتم التحقق من InResponseTo فقط إذا كان موجودًا في استجابة SAML الواردة.
* `OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED` و `OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED`
* عند ضبطه على `true` (الافتراضي)، يتوقع Overleaf أن تكون تأكيدات SAML، أو استجابة المصادقة SAML بالكامل، موقعة من قبل موفر الهوية. عندما تكون كلا الخيارين `false`، فيجب أن يكون أحد التأكيدات أو الاستجابة موقّعًا على الأقل.
* `OVERLEAF_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS`
* يحدد وقت انتهاء الصلاحية عندما لا يكون معرّف الطلب الذي تم إنشاؤه لطلب SAML صالحًا إذا ظهر في استجابة SAML في الحقل `InResponseTo` أيام. القيمة الافتراضية: 28800000 (8 ساعات).
* `OVERLEAF_SAML_LOGOUT_URL`
* عنوان الأساس الذي يتم استدعاؤه بطلبات تسجيل الخروج (الافتراضي: `entryPoint`).
* مثال: `https://idp.example.com/simplesaml/saml2/idp/SingleLogoutService.php`
* `OVERLEAF_SAML_ADDITIONAL_LOGOUT_PARAMS`
* قاموس JSON لمعلمات الاستعلام الإضافية لإضافتها إلى طلبات 'logout'.
* `OVERLEAF_SAML_IS_ADMIN_FIELD` و `OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE`
* عندما يكون كلا متغيري البيئة مضبوطين، تُحدّث عملية تسجيل الدخول `user.isAdmin = true` إذا كان ملف التعريف الذي يعيده موفر هوية SAML يحتوي على السمة المحددة بواسطة `OVERLEAF_SAML_IS_ADMIN_FIELD` وتطابقت قيمتها مع `OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE` أو كانت مصفوفة تحتوي على `OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE`، وإلا `user.isAdmin` يُضبط على `false`. إذا لم يُضبط أيٌّ من هذين المتغيرين، فلا تُضبط حالة المسؤول إلا على `true` أثناء إنشاء مستخدم مسؤول في Launchpad.
**البيانات الوصفية لموفر الهوية**
تتضمن النسخة الحالية من Overleaf CE نقطة نهاية لاسترجاع بيانات وصفية لموفر الخدمة: `http://my-overleaf-instance.com/saml/meta`
سيحتاج موفر الهوية إلى تهيئته للتعرف على خادم Overleaf باعتباره "موفر خدمة". راجع وثائق خادم SAML لديك للحصول على تعليمات حول كيفية القيام بذلك.
فيما يلي مثال على بيانات وصفية مناسبة لموفر الخدمة:
ol-meta.xml
```
MII...
[skipped]
MII...
[skipped]
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
```
لاحظ الشهادات، `AssertionConsumerService.Location`, `SingleLogoutService.Location` و `EntityDescriptor.entityID` وقم بتعيينها بالشكل المناسب في إعدادات موفر الهوية لديك، أو أرسل ملف البيانات الوصفية إلى مسؤول موفر الهوية.
ملف variables.env نموذجي (الحد الأدنى)
OVERLEAF_APP_NAME="مثيل أوفرليف الخاص بنا"
ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url
# يفعّل إنشاء الصور المصغّرة باستخدام ImageMagick
ENABLE_CONVERSIONS=true
# يعطّل متطلب تأكيد البريد الإلكتروني
EMAIL_CONFIRMATION_DISABLED=true
## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768
## اضبطه لـ TLS عبر nginx-proxy
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true
OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=مثيل Overleaf الخاص بنا
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
OVERLEAF_ADMIN_EMAIL=support@example.com
OVERLEAF_LEFT_FOOTER=[{"text": "تواصل مع فريق الدعم الخاص بك", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"مرحبًا، أنا على اليمين", "url":"https://github.com/yu-i-i/overleaf-cep"}]
OVERLEAF_EMAIL_FROM_ADDRESS=team@example.com
OVERLEAF_EMAIL_SMTP_HOST=smtp.example.com
OVERLEAF_EMAIL_SMTP_PORT=587
OVERLEAF_EMAIL_SMTP_SECURE=false
# OVERLEAF_EMAIL_SMTP_USER=
# OVERLEAF_EMAIL_SMTP_PASS=
# OVERLEAF_EMAIL_SMTP_NAME=
OVERLEAF_EMAIL_SMTP_LOGGER=false
OVERLEAF_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
OVERLEAF_EMAIL_SMTP_IGNORE_TLS=false
OVERLEAF_CUSTOM_EMAIL_FOOTER=يُدار هذا النظام بواسطة القسم x
OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true
#################
## SAML ##
#################
EXTERNAL_AUTH=saml
OVERLEAF_SAML_ISSUER=MyOverleaf
OVERLEAF_SAML_IDENTITY_SERVICE_NAME='Log in with SAML Provider'
OVERLEAF_SAML_EMAIL_FIELD=Email
OVERLEAF_SAML_FIRST_NAME_FIELD=DisplayName
OVERLEAF_SAML_LAST_NAME_FIELD=DisplayName
OVERLEAF_SAML_ENTRYPOINT=http://localhost:18000/login/saml/authorize/admin/SAML_Overleaf
OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem
OVERLEAF_SAML_SIGNATURE_ALGORITHM=
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://overleaf-pro.ayaka.space/on-premises/ar/aliadadat/overleaf-toolkit/authentication/saml-authentication.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.