مصادقة SAML

طُوّرت هذه الميزة بواسطة yu-i-i/overleaf-cep. نقدّم هنا بعض المستندات لمساعدتك في الإعداد.

الإعداد

داخليًا، تستخدم وحدة SAML في Overleaf مكتبة passport-saml، وتُمرَّر معظم خيارات الإعداد التالية إلى passport-saml. إذا واجهت مشكلات في إعداد SAML، فمن المفيد قراءة ملف README الخاص بـ passport-saml لتكوين فكرة عن الإعدادات التي تتوقعها. متغير البيئة EXTERNAL_AUTH مطلوب لتفعيل وحدة مصادقة SAML. يحدد هذا المتغير طرق المصادقة الخارجية المفعّلة. قيمة هذا المتغير عبارة عن قائمة. إذا تضمنت القائمة saml، فسيتم تفعيل مصادقة SAML. على سبيل المثال: EXTERNAL_AUTH=ldap saml عند استخدام طريقة مصادقة SAML، تتم إعادة توجيه المستخدم إلى موقع المصادقة الخاص بمزوّد الهوية (IdP). إذا نجح مزوّد الهوية في مصادقة المستخدم، يتم البحث في قاعدة بيانات مستخدمي Overleaf عن سجل يحتوي على حقل samlIdentifiers بالبنية التالية:

samlIdentifiers: [
  {
    externalUserId: "...",
    providerId: "1",
    userIdAttribute: "..."
  }
]

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

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

ملاحظة: حاليًا، لا يُدعم سوى مزوّد هوية SAML واحد. الحقل providerId في samlIdentifiers مثبّت على القيمة '1'.

متغيرات البيئة

OVERLEAF_SAML_IDENTITY_SERVICE_NAME
- الاسم المعروض لخدمة الهوية، ويُستخدم في صفحة تسجيل الدخول (الافتراضي: Log in with SAML IdP).
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 (مطلوب)
- اسم المُصدِر (Issuer).
OVERLEAF_SAML_AUDIENCE
- الجمهور (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 الوارد. وهي مطلوبة عند إعداد نقطة نهاية البيانات الوصفية عندما تكون الاستراتيجية مهيأة باستخدام 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
- مسار ملف يحتوي على شهادة عامة، وتُستخدم لـ نقطة نهاية البيانات الوصفية.
OVERLEAF_SAML_DECRYPTION_PVK
- مسار ملف يحتوي على مفتاح خاص مطابق لـ OVERLEAF_SAML_DECRYPTION_CERT، وسيُستخدم لمحاولة فك تشفير أي تأكيدات (assertions) مشفّرة يتم استلامها.
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_USER_ID_FIELD، الذي يمكن تعيينه مثلًا إلى عنوان البريد الإلكتروني للمستخدم.
OVERLEAF_SAML_ACCEPTED_CLOCK_SKEW_MS
- مقدار انحراف الساعة المقبول بالمللي ثانية بين العميل والخادم عند التحقق من صلاحية الطوابع الزمنية لشرطي التأكيد OnBefore وNotOnOrAfter. يؤدي تعيين القيمة إلى -1 إلى تعطيل التحقق من هذه الشروط بالكامل. القيمة الافتراضية هي 0.
OVERLEAF_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX
- السمة AttributeConsumingServiceIndex التي تُضاف إلى AuthnRequest لإرشاد مزوّد الهوية إلى مجموعة السمات التي يجب إرفاقها بالاستجابة (رابط).
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 الواردة.
- إذا كانت القيمة never، فلن يتم التحقق من 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
- يحدد مدة الصلاحية التي بعدها لا يعود معرّف الطلب (Request ID) المُنشأ لطلب SAML صالحًا إذا ظهر في الحقل InResponseTo في استجابة SAML. الافتراضي: 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 بوصفه “مزوّد خدمة” (Service Provider). راجع توثيق خادم SAML لديك للحصول على تعليمات حول كيفية القيام بذلك. فيما يلي مثال على بيانات وصفية مناسبة لمزوّد الخدمة:

ol-meta.xml

<?xml version="1.0"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
                  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
                  entityID="MyOverleaf"
                  ID="_b508c83b7dda452f5b269383fb391107116f8f57">
  <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" AuthnRequestsSigned="true" WantAssertionsSigned="true">
    <KeyDescriptor use="signing">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MII...
[skipped]
</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </KeyDescriptor>
    <KeyDescriptor use="encryption">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MII...
[skipped]
</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
      <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#aes256-gcm"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#aes128-gcm"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
    </KeyDescriptor>
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                         Location="https://my-overleaf-instance.com/saml/logout/callback"/>
    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
    <AssertionConsumerService index="1"
                              isDefault="true"
                              Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                              Location="https://my-overleaf-instance.com/saml/login/callback"/>
  </SPSSODescriptor>
</EntityDescriptor>

لاحظ الشهادات وAssertionConsumerService.Location وSingleLogoutService.Location وEntityDescriptor.entityID، وعيّنها بما يناسب في إعدادات مزوّد الهوية لديك، أو أرسل ملف البيانات الوصفية إلى مسؤول مزوّد الهوية.

نموذج لملف variables.env (الحد الأدنى)

OVERLEAF_APP_NAME="Our Overleaf Instance"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# Enables Thumbnail generation using ImageMagick
ENABLE_CONVERSIONS=true

# Disables email confirmation requirement
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## Set for TLS via nginx-proxy
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true

OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=Our Overleaf Instance
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
OVERLEAF_ADMIN_EMAIL=support@example.com

OVERLEAF_LEFT_FOOTER=[{"text": "Contact your support team", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Hello, I am on the Right", "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=This system is run by department 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=

دليل خطوة بخطوة: goauthentik

يشرح هذا الدليل إعدادًا تم اختباره مع goauthentik. استبدل https://overleaf.example.com بقيمة OVERLEAF_SITE_URL الخاصة بك، وhttps://authentik.example.com بعنوان Authentik الخاص بك.

أنشئ المزوّد والتطبيق

في Authentik، افتح Applications > Applications وانقر على New Application. ينشئ المعالج التطبيق والمزوّد الخاص به معًا.1. امنح التطبيق اسمًا وslug، على سبيل المثال overleaf، ثم انقر على Next:

2. اختر SAML Provider ثم انقر على Next:

3. املأ بيانات المزوّد:

Authorization Flow: default-provider-authorization-implicit-consent
ACS URL: https://overleaf.example.com/saml/login/callback
Audience: اسم لـ Overleaf، على سبيل المثال overleaf. يرسله Overleaf بوصفه OVERLEAF_SAML_ISSUER.

4. افتح Advanced protocol settings واضبط:

Signing Certificate: شهادة، على سبيل المثال authentik Self-signed Certificate
Sign assertions وSign responses: كلاهما مفعّل
Service Provider Binding: Post

Authentik: التوقيع والربط (binding) لمزوّد مُختبَر (نسخة اختبارية)

5. انقر على Next حتى الصفحة الأخيرة ثم أرسل التطبيق.

انسخ القيم من صفحة المزوّد

افتح المزوّد مرة أخرى. كل ما يحتاجه Overleaf موجود في صفحة النظرة العامة الخاصة به:

Authentik: نظرة عامة على مزوّد SAML (نسخة اختبارية)

في صفحة المزوّد	متغير البيئة
SAML Endpoint	`OVERLEAF_SAML_ENTRYPOINT` و`OVERLEAF_SAML_LOGOUT_URL`
Audience	`OVERLEAF_SAML_ISSUER`
Download signing certificate (ملف)	`OVERLEAF_SAML_IDP_CERT`، انظر الخطوة التالية

EntityID/Issuer ضمن SAML Configuration هو اسم Authentik نفسه. لا تضعه في OVERLEAF_SAML_ISSUER، بل استخدم Audience.

ثبّت شهادة التوقيع

انقر على Download تحت Download signing certificate واحفظ الملف باسم data/overleaf/certs/idp_cert.pem في مجلد Toolkit الخاص بك. تراه الحاوية على أنه /var/lib/overleaf/certs/idp_cert.pem:

OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem

اربط السمات

يرسل Authentik سماته بهذه الأسماء:

OVERLEAF_SAML_USER_ID_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_EMAIL_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
OVERLEAF_SAML_FIRST_NAME_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
OVERLEAF_SAML_LAST_NAME_FIELD=http://schemas.goauthentik.io/2021/02/saml/username

تصل المجموعات بوصفها http://schemas.xmlsoap.org/claims/Group، وهي قائمة. لجعل أعضاء مجموعة Authentik Admins مسؤولين في Overleaf:

OVERLEAF_SAML_IS_ADMIN_FIELD=http://schemas.xmlsoap.org/claims/Group
OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE=Admins

يتم تحديث علامة المسؤول عند كل تسجيل دخول عبر SAML. إذا كان الحقل أو القيمة خاطئًا، فسيفقد كل مسؤول يسجّل الدخول عبر SAML صلاحيات المسؤول. اختبر الربط أولًا بحساب مسؤول ثانٍ.

ملف variables.env مُختبَر لـ goauthentik

variables.env

EXTERNAL_AUTH=saml
OVERLEAF_SAML_IDENTITY_SERVICE_NAME=Log in with Authentik
OVERLEAF_SAML_ENTRYPOINT=https://authentik.example.com/application/saml/overleaf/
OVERLEAF_SAML_LOGOUT_URL=https://authentik.example.com/application/saml/overleaf/
OVERLEAF_SAML_ISSUER=overleaf
OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem
OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED=true
OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED=true
OVERLEAF_SAML_USER_ID_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_EMAIL_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
OVERLEAF_SAML_FIRST_NAME_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
OVERLEAF_SAML_LAST_NAME_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_IS_ADMIN_FIELD=http://schemas.xmlsoap.org/claims/Group
OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE=Admins
OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN=true

نظرة عامة

التثبيت

الإعداد

الصيانة

إدارة المستخدمين والمشاريع

الدعم

الإعداد

متغيرات البيئة

دليل خطوة بخطوة: goauthentik

​الإعداد

​متغيرات البيئة

​دليل خطوة بخطوة: goauthentik

الإعداد

متغيرات البيئة

دليل خطوة بخطوة: goauthentik