إعداد تكامل Okta

نظرة عامة

يمكن لـ Okta تقديم بيانات موحّدة عن دورة حياة المستخدم والمصادقة والمصادقة متعددة العوامل (MFA) والنشاط الإداري. تشمل الأمثلة التي تمت مراجعتها ما يلي:

account.locked — تم قفل الحساب
mfa.factor.activated — تفعيل عوامل MFA إضافية
auth.login.failed — فشل تسجيل الدخول

تقرأ طريقتا الاتصال كلتاهما التدفقين نفسيهما — دليل المستخدمين (/api/v1/users) وسجل النظام (/api/v1/logs). راجع كيف تتحول بيانات التكامل إلى إشارات.

اختيار طريقة الاتصال

	Okta (SSWS)	Okta (OAuth 2.0)
بيانات الاعتماد	رمز API تنشئه في Admin Console	معرف عميل ومفتاح JWK خاص تقوم بإنشائه وتسجيله
الإعداد	ثلاث خطوات، دون الحاجة إلى إنشاء مواد مفاتيح	تسع خطوات، تشمل إنشاء زوج مفاتيح RSA
دور المسؤول المطلوب	مسؤول بصلاحيات القراءة فقط، يُسند إلى مالك الرمز	مسؤول بصلاحيات القراءة فقط، يُسند إلى التطبيق
مدة صلاحية الرمز	يتم تعطيله بعد 30 يومًا من عدم الاستخدام	لا تنتهي صلاحيته؛ وتقع عليك مسؤولية تدوير زوج المفاتيح
متى تستخدمها	هذا هو المسار الموصى به لمعظم المؤسسات	تمنع سياسة الأمن لديك استخدام رموز API طويلة الأمد

تتطلب الطريقتان مستوى الوصول نفسه، لذا يتعلق الاختيار بآلية التعامل مع بيانات الاعتماد، لا بما يمكن للمنصة قراءته.

الخيار A — رمز API ‏(SSWS)

موصى به.

ما تحتاجه Living Security

بيانات الاعتماد	الوصف
API key	رمز API من Okta. تسمّي نافذة الاتصال هذا الحقل API key
Tenant subdomain	`<tenant>` في `<tenant>.okta.com` — النطاق الفرعي فقط، وليس عنوان URL الكامل

المتطلبات المسبقة

يجب أن تكون Super Administrator في Okta لإنشاء مستخدم حساب خدمة، وإسناد أدوار المسؤولين، وإنشاء رموز API.

إنشاء مستخدم يمتلك الرمز

يحمل رمز API في Okta صلاحيات المستخدم الذي أنشأه، ويتوقف عن العمل إذا تم تعطيل ذلك المستخدم. أنشئ حساب خدمة مخصصًا بدلًا من استخدام حساب مسؤول شخصي، حتى يستمر الاتصال عند تغيّر الموظفين.

في Admin Console، انتقل إلى Directory → People.
انقر على Add person وأنشئ مستخدمًا مثل svc-livingsecurity@yourcompany.com.
فعّل الحساب.

إسناد دور المسؤول بصلاحيات القراءة فقط

تقوم المنصة بالقراءة فقط. ومنح صلاحيات تتجاوز القراءة يمنح الرمز أذونات لا يستخدمها أبدًا.

انتقل إلى Security → Administrators.
انقر على Add administrator وحدد المستخدم الذي أنشأته في الخطوة السابقة.
أسند دور Read-only Administrator.
احفظ.

بدون دور مسؤول، تنجح استدعاءات Okta Management API بالرمز 200 OK وتعيد قائمة فارغة. ولا يوجد 403 يُنبّهك إلى غياب الدور — بل تبقى التدفقات فارغة ببساطة.

إنشاء رمز API

سجّل الدخول إلى Admin Console بصفتك مستخدم حساب الخدمة الذي أنشأته في الخطوة 1. يرث الرمز صلاحيات الحساب الذي ينشئه.
انتقل إلى Security → API وافتح علامة التبويب Tokens.
انقر على Create token، وأعطه اسمًا مثل Living Security Platform، ثم انقر على Create token.
انسخ قيمة الرمز الآن — تعرضها Okta مرة واحدة فقط ولن تعرضها مجددًا.

تعطّل Okta رمز API بعد 30 يومًا من عدم الاستخدام. تعمل عمليات المزامنة في هذا التكامل مرة واحدة على الأقل يوميًا، لذا يحافظ الاتصال النشط على صلاحية رمزه. أما الاتصال الذي يُترك متوقفًا لمدة شهر فيحتاج إلى رمز جديد.

لا تهمّك قائمة العناوين أعلاه إلا إذا كانت مؤسسة Okta لديك تقيّد الوصول إلى API حسب network zone. ولا تفعل معظم المؤسسات ذلك.

العثور على النطاق الفرعي للمستأجر

يبدو عنوان URL الخاص بـ Admin Console لديك كما يلي: https://acme-admin.okta.com. النطاق الفرعي للمستأجر هو acme — بدون اللاحقة -admin، وبدون .okta.com، وبدون https://.

لقد تم الآن الاتصال بـ Okta (SSWS).

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

401 Unauthorized

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

تم الاتصال، لكن جميع التدفقات فارغة

لا يملك مالك الرمز دور مسؤول. أسند دور Read-only Administrator إلى حساب الخدمة (الخطوة 2) — تعيد API الرمز 200 OK مع قائمة فارغة بدلًا من خطأ عندما يكون الدور مفقودًا.

فشل عمليات المزامنة بعد تغيّر الموظفين

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

الخيار B — تطبيق خدمة OAuth 2.0

استخدم هذه الطريقة عندما لا تسمح سياسة الأمن لديك برموز API طويلة الأمد. فهي تستبدل الرمز بمعرف عميل وزوج مفاتيح RSA تملكه. في المنصة، هذه هي البطاقة Okta (OAuth 2.0) ضمن الإعدادات ← التكاملات ← كتالوج. للمصادقة مع Okta باستخدام Client Credentials، تحتاج إلى ما يلي:

Client ID - معرّف فريد لتطبيق Okta API Services الخاص بك.
Private Key (JWK) - مفتاح RSA الخاص بصيغة JSON Web Key، والذي يكون مفتاحه العام مسجلًا في تطبيق Okta الخاص بك.
Okta Domain - النطاق الفرعي لمستأجر Okta فقط (مثل dev-12345678)، وليس اسم المضيف الكامل.
Scopes - قائمة مفصولة بمسافات من نطاقات Okta Management API (مثل okta.users.read okta.logs.read).

سيرشدك هذا الدليل خلال إنشاء تطبيق API Services في Okta مع مصادقة private_key_jwt.

المتطلبات المسبقة:

يجب أن يكون لديك حساب Okta. يمكنك التسجيل للحصول على حساب مطوّر مجاني على developer.okta.com.

الخطوة 1: إنشاء تطبيق Okta API Services

سجّل الدخول إلى Okta Admin Console.
في الشريط الجانبي الأيسر، انتقل إلى Applications > Applications.
انقر على Create App Integration.
حدد API Services كطريقة تسجيل الدخول وانقر على التالي.

أعطِ تطبيقك اسمًا وانقر على حفظ.
في علامة التبويب General الخاصة بالتطبيق، ابحث عن معرف العميل — ستحتاج إليه في الخطوة الأخيرة.
اضبط Client authentication على Public key / Private key. لا تُدعم نطاقات okta.* إلا مع طريقة المصادقة هذه.

عطّل Proof of possession (DPoP) — فهو غير مدعوم.

يجب إنشاء التطبيق من النوع API Services.

الخطوة 2: إنشاء زوج مفاتيح RSA وتسجيله

استخدام مولّد المفاتيح في Okta

يمكن لـ Okta إنشاء زوج مفاتيح RSA لك مباشرة في Admin Console:

في Admin Console، افتح تطبيق API Services الخاص بك.
انتقل إلى علامة التبويب General ومرّر إلى قسم PUBLIC KEYS.
انقر على Add Key، ثم حدد Generate new key.
انقر على حفظ — تنشئ Okta زوج المفاتيح وتعرض Private Key (JWK) مرة واحدة.
انسخ ملف JSON الخاص بالمفتاح الخاص واحفظه فورًا — فلن يُعرض مرة أخرى.

يتم تسجيل المفتاح العام تلقائيًا في تطبيقك.

انسخ مفتاح JWK الخاص قبل إغلاق مربع الحوار. والصقه في حقل Private Key في Living Security Platform في الخطوة الأخيرة.

إنشاء مفتاحك الخاص

تستخدم Okta private_key_jwt لتطبيقات API Services. تقوم بإنشاء زوج مفاتيح RSA، وتسجّل مفتاح JWK العام لدى Okta، وتزوّد Living Security Platform بمفتاح JWK الخاص. أنشئ مفتاح JWK خاصًا باستخدام نص Node.js البرمجي التالي (يتطلب Node.js 18+):

const { generateKeyPairSync } = require('crypto');
const { privateKey, publicKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });

const privateJwk = privateKey.export({ format: 'jwk' });
const publicJwk  = publicKey.export({ format: 'jwk' });

// Assign a kid — must match between private and public JWK
const kid = require('crypto').randomUUID();
privateJwk.kid = kid;
publicJwk.kid  = kid;

console.log('=== PUBLIC JWK (upload to Okta) ===');
console.log(JSON.stringify(publicJwk, null, 2));
console.log('\n=== PRIVATE JWK (paste into the Living Security Platform) ===');
console.log(JSON.stringify(privateJwk));

سجّل مفتاح JWK العام في Okta:

في Admin Console، افتح تطبيق API Services الخاص بك.
انتقل إلى علامة التبويب General ومرّر إلى قسم PUBLIC KEYS.
انقر على Add Key، والصق ناتج JSON لمفتاح JWK العام من النص البرمجي أعلاه، ثم انقر على حفظ.

مفتاح JWK الخاص هو ما تلصقه في Living Security Platform. ويتضمن جميع مواد المفتاح (d، p، q، dp، dq، qi) وkid. حافظ على سريته.

الخطوة 3: العثور على Okta Domain

أدخل النطاق الفرعي لمستأجر Okta فقط — الجزء الذي يسبق .okta.com.

في Admin Console، سيعرض شريط عنوان المتصفح عنوان URL مثل https://dev-12345678-admin.okta.com.
Okta Domain الخاص بك هو النطاق الفرعي فقط (مثل dev-12345678)، وليس dev-12345678.okta.com.
بدلًا من ذلك، انتقل إلى الإعدادات > Account في Admin Console للعثور على نطاق Okta الخاص بك، ثم استخدم جزء النطاق الفرعي.

الخطوة 4: منح نطاقات API لتطبيقك

تشترط Okta وجود نطاق واحد على الأقل في كل طلب رمز. قبل أن يتمكن تطبيقك من طلب نطاقات محددة، يجب منحها:

في Admin Console، انتقل إلى Applications > Applications وافتح تطبيقك.
انقر على علامة التبويب Okta API Scopes.
امنح النطاقات التي يتطلبها تكاملك: okta.users.read وokta.logs.read.

توجد قائمة كاملة بالنطاقات المتاحة في مرجع Okta Management API.

الخطوة 5: إسناد دور مسؤول إلى تطبيقك

منح النطاقات وحده لا يكفي — إذ تعيد نقاط نهاية Okta Management API (مثل /api/v1/users) استجابة 200 [] فارغة دون أي تنبيه إذا لم يكن لتطبيقك دور مسؤول. يجب إسناد Read-Only Administrator على الأقل:

في Admin Console، انتقل إلى الأمن > Administrators (أو انتقل إلى Applications > Applications > تطبيقك > Admin roles).
انقر على Add administrator assignment وحدد تطبيق API Services الخاص بك.

أسند دور Read-Only Administrator (أو دورًا أعلى، بحسب النطاقات التي تحتاجها).
انقر على حفظ.

بدون دور مسؤول، تنجح استدعاءات API بالرمز 200 OK لكنها تعيد نتائج فارغة، ولا يوجد خطأ 403 يشير إلى المشكلة.

الخطوة 6: إدخال بيانات الاعتماد في Living Security Platform

بعد أن تحصل على معرف العميل وPrivate Key (JWK) وOkta Domain وScopes:

افتح النموذج الذي تحتاج فيه إلى المصادقة مع Okta (Client Credentials).
أدخل معرف العميل.
الصق Private Key (JWK) — كائن JSON الكامل من النص البرمجي أعلاه (في سطر واحد أو منسّقًا).
أدخل Okta Domain على أنه النطاق الفرعي للمستأجر فقط (مثل dev-12345678).
أدخل Scopes كقائمة مفصولة بمسافات (مثل okta.users.read okta.logs.read).
أرسل النموذج، ومن المفترض أن تتم المصادقة بنجاح.

لقد تم الآن الاتصال بـ Okta (Client Credentials).

تم اقتباس أجزاء من هذا التوثيق بتصرف من Nango، وهي مستخدمة بموجب Elastic License 2.0.

التكاملات

إعداد التكامل

الكتالوج

القنوات الصادرة

نظرة عامة

اختيار طريقة الاتصال