‫Pocket ID‬: مزود ‫OIDC‬ خفيف في حاوية واحدة

لماذا تستضيف مزود ‫OIDC‬ بنفسك

ما تحصل عليه مع ‫OIDC IdP‬ ذاتي الاستضافة

• هوية مركزية — حساب واحد لـ‫Gitea‬ و‫Nextcloud‬ و‫Grafana‬ وجميع الخدمات المتوافقة مع ‫OIDC‬.
• إلغاء شامل — تعطيل حساب في ‫Pocket ID‬ يقطع الوصول إلى جميع التطبيقات المتصلة عند تجديد الرمز التالي.
• مصادقة بمفاتيح المرور — ‫Touch ID‬ أو ‫Face ID‬ أو مفتاح ‫FIDO2‬ كعامل وحيد، دون كلمة مرور تُنقل.
• لا اعتماد على السحابة — تبقى هوياتك تحت ولايتك القضائية، دون حصص مستخدمين أو تسعير لكل طلب.
• بصمة دنيا — يستهلك ‫Pocket ID‬ أقل من ‫50 MB‬ من الذاكرة في وضع الخمول، مقارنة بـ‫300–600 MB‬ لـ‫Authentik‬ و‫1–2 GB‬ لـ‫Keycloak‬.
• ‫SQLite‬ مدمج — لا حاجة لمحرك قاعدة بيانات خارجية.
• ‫Back-channel logout‬ (الإصدار ‫v2.18.0‬) — عند تعطيل مستخدم أو إلغاء عميل، يُخطر ‫Pocket ID‬ التطبيقات المسجلة ويُبطل جلساتها من جانب الخادم.
• حاوية واحدة — الخدمة بأكملها في صورة ‫Docker‬ بحجم ‫~30 MB‬، دون تبعية ‫Redis‬ أو عامل منفصل.

المتطلبات الرقمية

تثبيت Pocket ID

1. 01

   إعداد خادم VPS والنطاق

   اطلب خادم ‫VPS‬ يعمل بـ‫Ubuntu 22.04‬ أو ‫Debian 12‬ بذاكرة ‫512 MB RAM‬ على الأقل. أنشئ سجل ‫DNS‬ من النوع ‫A‬ يشير auth.your-domain.com إلى عنوان ‫IP‬ الخادم.

   ثبّت ‫Docker‬ وإضافة ‫Compose‬:

   curl -fsSL https://get.docker.com | sh

2. 02

   إنشاء دليل العمل

   على الخادم، أنشئ دليلاً مخصصاً:

   mkdir -p /opt/pocket-id && cd /opt/pocket-id

3. 03

   كتابة ملف docker-compose.yml

   أنشئ /opt/pocket-id/docker-compose.yml:

   services:
     pocket-id:
       image: ghcr.io/pocket-id/pocket-id:v2.18.0
       container_name: pocket-id
       restart: unless-stopped
       ports:
         - "1411:1411"
       volumes:
         - ./data:/app/data
       environment:
         APP_URL: "https://auth.your-domain.com"
         TRUST_PROXY: "true"

4. 04

   إعداد البروكسي العكسي nginx

   أنشئ الإعداد لـauth.your-domain.com. يستمع ‫Pocket ID‬ على ‫HTTP‬ على المنفذ ‫1411‬؛ يتولى البروكسي العكسي معالجة ‫TLS‬.

   server {
       listen 443 ssl http2;
       server_name auth.your-domain.com;
   
       ssl_certificate     /etc/letsencrypt/live/auth.your-domain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/auth.your-domain.com/privkey.pem;
   
       proxy_buffer_size   256k;
       proxy_buffers       4 512k;
       proxy_busy_buffers_size 512k;
   
       location / {
           proxy_pass         http://127.0.0.1:1411;
           proxy_set_header   Host              $host;
           proxy_set_header   X-Real-IP         $remote_addr;
           proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
           proxy_set_header   X-Forwarded-Proto $scheme;
       }
   }

   احصل على الشهادة باستخدام ‫Certbot‬:

   certbot certonly --nginx -d auth.your-domain.com
   nginx -t && systemctl reload nginx

5. 05

   تشغيل الحاوية

   من /opt/pocket-id:

   docker compose up -d
   docker compose logs -f pocket-id

   يؤكد سطر السجل Starting Pocket ID on :1411 أن الخادم جاهز. زُر https://auth.your-domain.com لإتمام الإعداد الأولي.

6. 06

   إنشاء حساب المسؤول وتسجيل مفتاح مرور

   في الزيارة الأولى، يطلب ‫Pocket ID‬ إنشاء حساب المسؤول. أدخل بريدك الإلكتروني، ثم سجّل مفتاح مرور فوراً: انتقل إلى الإعدادات → مفاتيح المرور → إضافة واتبع مطالبة المتصفح (‫Touch ID‬ أو ‫Windows Hello‬ أو مفتاح ‫FIDO2‬).

7. 07

   تسجيل أول تطبيق OIDC

   في واجهة الإدارة، افتح عملاء OIDC → عميل جديد. أدخل:
   - الاسم: معرّف مقروء للتطبيق (مثل Gitea)
   - عنوان URL للاستدعاء: عنوان إعادة التوجيه المُعلن في التطبيق العميل

   يُنشئ ‫Pocket ID v2.18.0‬ تلقائياً client_secret عند الإنشاء — استرجعه فوراً.

   لاحظ Client ID وعنوان الاكتشاف https://auth.your-domain.com/.well-known/openid-configuration.

8. 08

   اختبار التدفق من التطبيق العميل

   في ‫Gitea‬، انتقل إلى الإدارة → مصادر المصادقة → إضافة → OAuth2. اختر ‫OpenID Connect‬ كمزود، وأدخل Client ID وClient Secret وعنوان الاكتشاف. شغّل اختبار تسجيل دخول: يجب أن يُعاد توجيه المتصفح إلى auth.your-domain.com، ويطلب مفتاح المرور المسجل، ثم يُعيد التوجيه إلى ‫Gitea‬ مع تسجيل دخول المستخدم.

الإعداد بعد التثبيت

استكشاف الأخطاء وإصلاحها

الأخطاء الشائعة وحلولها

• 502 Bad Gateway على جميع الصفحات — السبب الأكثر شيوعاً: مخازن ‫nginx‬ المؤقتة صغيرة جداً لرؤوس استجابة ‫OIDC‬ في ‫Pocket ID‬. أضف proxy_buffer_size 256k وproxy_buffers 4 512k وproxy_busy_buffers_size 512k في كتلة location / وأعد تحميل ‫nginx‬.
• redirect_uri_mismatch أثناء تسجيل الدخول — عنوان ‫Callback URL‬ المُعلن في ‫Pocket ID‬ لا يتطابق تماماً مع ذلك الذي يرسله التطبيق العميل. تحقق من وجود شرطة مائلة في النهاية، والمخطط http مقابل https، ورقم المنفذ.
• invalid_client عند تبادل الرمز — client_secret الذي يرسله التطبيق لا يتطابق. في ‫v2.18.0‬، يُنشئ ‫Pocket ID‬ سراً تلقائياً عند إنشاء العميل؛ إن لم تحفظه، أعد إنشاء واحد من سجل العميل في لوحة الإدارة.
• رفض مفتاح المرور: NotAllowedError — المتصفح لا يمكنه الوصول إلى واجهات ‫WebAuthn‬ بدون ‫HTTPS‬. تحقق من أن APP_URL مضبوط على https://... وأن شهادة ‫TLS‬ صالحة.
• عدم إبطال الجلسات بعد الإلغاء — يتطلب ‫back-channel logout‬ أن يُعلن التطبيق العميل Backchannel Logout URL في سجل ‫OIDC‬ الخاص به. تحقق من ملء هذا الحقل وإمكانية الوصول إليه من حاوية ‫Pocket ID‬.

‫Pocket ID‬ أم ‫Authentik‬ أم ‫Keycloak‬ أم ‫Authelia‬: أيّ تختار

مرّر الجدول أفقيًا

خلاصة