تكوين حسابات ISE Guest مع REST API

المقدمة

يوضح هذا المستند كيفية إستخدام ميزة واجهة برمجة التطبيقات (API) لنقل الحالة التمثيلية (REST) لأداء المهام المتعلقة بالضيف على محرك خدمات الهوية (ISE). واجهة برمجة تطبيقات Cisco Guest هي مجموعة عمليات قائمة على REST توفر بروتوكول HTTPS الآمن والوصول المصدق عليه لإدارة مستخدمي Cisco Guest. باستخدام واجهة برمجة التطبيقات (API)، يمكن إنشاء المستخدمين الضيوف وقراءتهم وتحديثهم وحذفهم والبحث عنهم.

المتطلبات الأساسية

المتطلبات

cisco يوصي أن يتلقى أنت معرفة من هذا موضوع:

• محرك خدمات كشف الهوية (ISE)
• خدمات الراحة الخارجية
• راحة العملاء مثل الأرق، الراحة، الخ.

المكونات المستخدمة

تستند المعلومات الواردة في هذا المستند إلى إصدارات البرامج والمكونات المادية التالية:

• Cisco ISE، الإصدار 2.6
• Ennia REST Client الإصدار 7.1.1

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

ملاحظة: يكون الإجراء مماثلا أو متطابقا مع إصدارات ISE الأخرى. يمكنك إستخدام هذه الخطوات على جميع إصدارات برنامج 2.x ISE Software ما لم ينص على خلاف ذلك.

معلومات أساسية

لاستخدام واجهة برمجة التطبيقات (API)، يجب تمكين "خدمات الراحة الخارجية" (ERS) وتبني المصادقة في ISE. يدعم ERS المصادقة الأساسية ويتم تشغيله عبر المنفذ 9060. يتم تشفير بيانات اعتماد المصادقة وهي جزء من رأس الطلب. يتطلب ERS من مسؤول ISE تعيين امتيازات خاصة لمستخدم لإجراء عمليات.

سيغطي المستند خطوات التكوين التالية:

1. تمكين ERS على ISE

2. إعداد حساب المسؤول والضامن ل ERS

3. إنشاء حساب ضيف

4. قراءة بيانات الضيوف وتحديثها وحذفها

التكوين

تمكين ERS على ISE

لاستخدام ميزة REST API على ISE، يجب تمكين ERS.

انتقل إلى إدارة > نظام > إعدادات > إعدادات > ERS > تمكين ERS للقراءة/الكتابة كما هو موضح في الصورة.

تتوفر جميع المعلومات المتعلقة بتطبيقات ERS كمجموعة أدوات تطوير البرامج (SDK) على المنفذ 9060 من ISE عبر بروتوكول HTTPS. يمكن الوصول إلى هذا بعد تمكين ERS وتسجيل الدخول باستخدام حساب مسؤول ذي امتيازات "ERS-Admin" أو "ERS-Operator".

إعداد حساب المسؤول والكفيل ل ERS

يتطلب ISE، لاستخدام ERS، حساب مسؤول له امتيازات ERS-Admin أو عامل تشغيل ERS المعين له. يلزم إنشاء حسابات المسؤول وإضافتها إلى المجموعات المعنية. بدلا من ذلك، يعمل وصول ERS لحساب Super-Admin أيضا.

من أجل إستخدام واجهات برمجة التطبيقات (API) لميزات الضيوف، يتطلب مسؤول ERS بيانات أولية للمداخل مثل معرف البوابة ومجموعات هوية الضيف وما إلى ذلك. ومع ذلك، فمن أجل قراءة/إنشاء/تحديث أو حذف أي بيانات ضيف، يلزم وجود حساب مقدم مع تمكين وصول ERS.

• لأغراض هذا المستند، يتم إستخدام حساب مستخدم ISE داخلي كمقدم خدمة.
• انتقل إلى إدارة > إدارة الهوية > الهويات وأضف مستخدم وصول إلى الشبكة كما هو موضح في الصورة.

• يجب إضافة حساب المستخدم هذا إلى إحدى مجموعات الكفلاء.
• يتم تعيين حساب المثال على مجموعة الكفيل الافتراضية المسماة ALL_ACCOUNTS. 
• من أجل السماح ل ERS بالوصول إلى هذه المجموعة التي ترعاها، انتقل إلى مراكز العمل > Guest Access (وصول الزائرين) > البوابة والمكونات > مجموعات العملاء وافتح مجموعة الكفلاء المعينة.
• تمكين الخيار: قم بالوصول إلى حسابات ضيف Cisco ISE باستخدام الواجهة البرمجية (واجهة برمجة تطبيقات Guest REST) كما هو موضح في الصورة.

إنشاء حساب ضيف

من أجل إنشاء حساب ضيف من خلال واجهة برمجة التطبيقات، من الضروري أن يتم إستدعاء واجهة برمجة التطبيقات (API) إلى ISE كراع ومن خلال بوابة ترعاها وتعترف بها.

الخطوة 1. من أجل إحضار معرفات البوابة الخاصة بجميع بوابات الكفيل التي تم تكوينها مسبقا على ISE، أستخدم أي عميل REST مع المعلومات الواردة هنا:

طريقة	إحضار
URL	https://<ISE-IP>:9060/ers/config/sponsorportal
بيانات الاعتماد	إستخدام بيانات اعتماد مسؤول ERS
العنوان الرئيسي	نوع المحتوى: التطبيق/xml قبول: التطبيق/xml

الناتج المتوقع:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns3:searchResult total="1"
xmlns:ns5="ers.ise.cisco.com"
xmlns:ers-v2="ers-v2"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns3="v2.ers.ise.cisco.com">
<ns3:resources>
<ns5:resource description="Default portal used by sponsors to create and manage accounts for authorized visitors to securely access the network" 
id="274a95f0-2e58-11e9-98fb-0050568775a3" name="Sponsor Portal (default)">
<link rel="self" href="https://10.127.197.186:9060/ers/config/sponsorportal/274a95f0-2e58-11e9-98fb-0050568775a3" type="application/xml"/>
</ns5:resource>
</ns3:resources>
</ns3:searchResult>

قيمة الفائدة هي معرف مدخل مدخل مدخل الكفيل الذي تم تصميمه ليتم إستخدامه لإنشاء المستخدمين الضيوف. المعرف هو "274a95f0-2e58-11e9-98fb-0050568775a3" في هذا المثال.

الخطوة 2. أستخدم إستدعاء واجهة برمجة التطبيقات هذا لإنشاء حساب ضيف. قيمة portalID هنا هي القيمة التي يتم إحضارها من الخطوة 1.

طريقة	الاختبار الذاتي لبدء التشغيل (POST)
URL	https://<ISE-IP>:9060/ers/config/guestuser/
بيانات الاعتماد	إستخدام بيانات اعتماد حساب الكفيل
العنوان الرئيسي	نوع المحتوى: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml قبول: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
نص الرسالة	<؟xml version="1.0" encoding="UTF-8"؟> <ns2:guestuser xmlns:ns2="identity.ers.ise.cisco.com"> <customFields> </customFields> <guestAccessInfo> <fromDate>04/25/2020 18:55</fromDate> <location>دلهي</location> <toDate>04/28/2020 19:55</toDate> <validDays>3</validDays> </guestAccessInfo> <guestInfo> <company>Cisco</company> <emailAddress>abcd@cisco.com</emailAddress> <firstName>جون</firstName> <lastName>Do</lastName> <notificationLanguage>الإنجليزية</notificationLanguage> <password>9618</password> <phoneNumber>999998877</phoneNumber> <smsServiceProvider>الافتراضي العام</smsServiceProvider> <userName>jumdoe</userName> </guestInfo> <guestType>المقاول (الافتراضي)</guestType> <personBeingVisit>abcd3@cisco.com</personBeingVisit> <portalId>274a95f0-2e58-11e9-98fb-005056875a3</portalId> <reasonForVisit>زيارة بوب من Accounting</reasonForVisit> </ns2:Guestuser>

ملاحظة: يمكن إستخدام محتوى النص الرئيسي المعروض هنا كقالب (متوفر في SDK أيضا). تأكد من توافق FromDate و ToDate مع ValidDays. يجب أن يكون الموقع ونوع الضيف وقيم أخرى صالحة بالإشارة إلى ISE المستخدم، وحينئذ فقط تنجح الاستدعاء.

ملاحظة: يجب أن تكون بيانات الاعتماد المستخدمة عند إجراء هذه المكالمة عبارة عن حساب كفيل صالح تم تعيينه إلى مجموعة كفلاء. لن تعمل بيانات اعتماد مسؤول ERS هنا. راجع القسم السابق من هذا الدليل للحصول على مزيد من التفاصيل.

الناتج المتوقع:

انتقل إلى واجهة المستخدم الرسومية (ISE) > Master GuestReport للتحقق من إنشاء الحساب:

ملاحظة: لا يوجد خيار لتحديد مجموعة اسم مستخدم وكلمة مرور مخصصة لكل حساب ضيف من بوابة تابعة للكفيل. يمكن إستخدام طريقة واجهة برمجة التطبيقات هذه للوفاء بهذا المتطلب.

قراءة بيانات الضيوف وتحديثها وحذفها

فيما يلي بعض الأمثلة على مكالمات واجهة برمجة التطبيقات (API) لتنفيذ إجراءات مختلفة على بيانات الضيوف. تتوفر جميع الخيارات المتاحة وتنسيقاتها في SDK.

• الحصول على تفاصيل حساب مستخدم ضيف حسب الاسم:

طريقة	إحضار
URL	https://<ISE-IP>:9060/ers/config/guestuser/name/{name}
بيانات الاعتماد	إستخدام بيانات اعتماد حساب الكفيل
العنوان الرئيسي	نوع المحتوى: التطبيق/xml قبول: التطبيق/xml

الناتج المتوقع:

200 OK

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns4:guestuser id="3b967932-86f8-11ea-aafe-72889dc971d1" name="johndoe"
xmlns:ers="ers.ise.cisco.com"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns4="identity.ers.ise.cisco.com">
<link rel="self" href="https://10.127.197.186:9060/ers/config/guestuser/name/johndoe" type="application/xml"/>
<customFields/>
<guestAccessInfo>
<fromDate>04/25/2020 18:55</fromDate>
<location>Delhi</location>
<toDate>04/28/2020 19:55</toDate>
<validDays>3</validDays>
</guestAccessInfo>
<guestInfo>
<company>Cisco</company>
<creationTime>04/25/2020 18:55</creationTime>
<emailAddress>abcd@cisco.com</emailAddress>
<enabled>false</enabled>
<firstName>John</firstName>
<lastName>Doe</lastName>
<notificationLanguage>English</notificationLanguage>
<password>9618</password>
<phoneNumber>9999998877</phoneNumber>
<smsServiceProvider>Global Default</smsServiceProvider>
<userName>johndoe</userName>
</guestInfo>
<guestType>Contractor (default)</guestType>
<personBeingVisited>abcd3@cisco.com</personBeingVisited>
<reasonForVisit>Visiting Bob from Accounting</reasonForVisit>
<sponsorUserId>1f7627f0-86f8-11ea-aafe-72889dc971d1</sponsorUserId>
<sponsorUserName>Sponsor_ERS</sponsorUserName>
<status>AWAITING_INITIAL_LOGIN</status>
</ns4:guestuser>

• إعادة تعيين كلمة مرور مستخدم ضيف:

يتطلب هذا إحضار معرف الضيف أولا من المكالمة ثم إستخدامه في واجهة برمجة التطبيقات هذه. معرف المستخدم guestuser هو "3b967932-86f8-11ea-aafe-72889dc971d1" في هذا المثال.

طريقة	PUT
URL	https://<ISE-IP>:9060/ers/config/guestuser/resetpassword/{id}
بيانات الاعتماد	إستخدام بيانات اعتماد حساب الكفيل
العنوان الرئيسي	نوع المحتوى: التطبيق/xml قبول: التطبيق/xml

لا يسمح هذا الأسلوب بتعيين كلمة المرور الجديدة. سيقوم ISE بإرجاع الإخراج باستخدام كلمة المرور الجديدة التي تم إنشاؤها تلقائيا.

الناتج المتوقع:

200 OK

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns3:operationResult
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns3="ers.ise.cisco.com">
<attributesList>
<attribute name="password" value="2557"/>
</attributesList>
</ns3:operationResult>

•  حذف حساب ضيف حسب الاسم:

طريقة	حذف
URL	https://<ISE-IP>:9060/ers/config/guestuser/name/{name}
بيانات الاعتماد	إستخدام بيانات اعتماد حساب الكفيل
العنوان الرئيسي	نوع المحتوى: التطبيق/xml قبول: التطبيق/xml

الناتج المتوقع:

التحقق من الصحة

لا يوجد حاليًا إجراء للتحقق من صحة هذا التكوين.

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

يوفر هذا القسم معلومات يمكنك إستخدامها لاستكشاف أخطاء التكوين وإصلاحها.

بعض الأخطاء الشائعة وأسبابها المحتملة:

• فشل إنشاء حساب ضيف مع حدوث خطأ:

     401 Unauthorized

     <message type="ERROR" code="CRUD operation exception">
    <title>Sponsor does not have permission to access REST Apis</title>
     </message>

الإصلاح: هذا يعني أن حساب الكفيل المستخدم لجعل حساب الضيف معين إلى مجموعة كفلاء حيث لم يتم تمكين وصول ERS. قم بتحرير مجموعة الكفيل التي تطابق هذا وتمكين الوصول إلى حسابات ضيف Cisco ISE باستخدام الواجهة البرنامجية (Guest REST API).

   400 Bad Request

   <message type="ERROR" code="CRUD operation exception">
    <title>Creating GuestUser failed due to com.cisco.cpm.guestaccess.validation.GuestAccessValidationException: Portal not found for portal session e1fc15a7-a170-4d6a-b02c-0ab7b0bc54ff</title>

الإصلاح: معرف المدخل الذي تم إدخاله في الاستدعاء غير موجود على ISE أو غير صحيح. من إستدعاء 'Get' لبوابة الكفيل، قم بجلب معرف المدخل الصحيح للمدخل.

• رموز إستجابة واجهة برمجة التطبيقات (API) ومعانيها المحتملة:

      200 (OK): يشير إلى أن REST API نفذت الإجراء المطلوب بنجاح.

      201 (إنشاء): يشير إلى أنه تم إنشاء مورد داخل مجموعة.

      204 (لا يوجد محتوى): يتم إرسال ذلك عادة كاستجابة لطلبات PUT أو POST أو DELETE.

     400 (طلب غير صحيح): رمز خطأ عام لمشاكل مثل بناء جملة طلب غير صحيح، معلمات غير صحيحة، إلخ. اقرأ تفاصيل الرسالة إذا كانت متوفرة لفهم السبب.

     401(غير مصرح به): يشير ذلك إلى أنه تم إتخاذ الإجراء باستخدام بيانات اعتماد خاطئة أو لا توجد بيانات اعتماد أو أن الحساب غير مصرح له بتنفيذ هذا الإجراء.

     500(خطأ في الخادم الداخلي): يشير إلى وجود مشكلة في جانب الخادم. قد تساعد السجلات على ISE في فهم السبب.

لمزيد من التفاصيل حول إستخدام REST API ل ISE، ارجع إلى Guest REST API.