تعرف على التصديق بين تطبيقات Java Oracle Identity Cloud Service و Oracle Identity Cloud Service

تعرف على تدفقات التصديق ثلاثية الأبعاد

يدعم Oracle Identity Cloud Service تدفق التصديق ثلاثي المحطات لـ Java SDK. في هذا التدفق ، يتفاعل المستخدمون مباشرة مع Oracle Identity Cloud Service. بعد قيام المستخدم بتسجيل الدخول ، يصدر Oracle Identity Cloud Service رمز اعتماد يخول SDK لمقطع وصول المستخدم. يستخدم تطبيق الويب Java مقطع الوصول هذا لمنح المستخدمين حق الوصول إلى الموارد المحمية في التطبيق. يستخدم التدفق المكون من ثلاث مراحل نوع منح رمز الصلاحية.

أما في حالة زيادة التأمين ، توصي Oracle باستخدام التدفق ثلاثي المحطات لتكامل تطبيقات ويب Java مع Oracle Identity Cloud Service للتصديق. باستخدام نوع منح رمز الاعتماد ، يمكنك أيضًا الوصول إلى التطبيقات الأخرى المحمية بواسطة Oracle Identity Cloud Service دون الحاجة إلى إعادة التصديق.

التعرف على حالات الاستخدام الأساسية لاستخدام SDK مع تطبيق Java

يقوم تطبيق الويب Java بتنفيذ حالتا استخدام: أحدهما للتصديق على المستخدمين ، والأخرى للوصول إلى معلومات تفصيلية عن المستخدم الذي قام بالدخول.

توضح مخططات تدفق البيانات التالية تدفق الأحداث والمكالمات والاستجابات بين مستعرض الويب وتطبيق الويب Oracle Identity Cloud Service لكل حالة استخدام.

استخدام الحالة #1: تصديق مستخدم

وصف الشكل التوضيحي authenticate-user.png

يحدث تدفق البيانات بهذه الطريقة:

يطلب المستخدم موردًا محميًا.
تستخدم الوحدة النمطية للتصديق SDK لإنشاء عنوان URL لطلب الاعتماد الخاص بـ Oracle Identity Cloud Service وإرسال عنوان URL هذا كاستجابة إعادة التوجيه إلى متصفح الويب.
يستدعي مستعرض الويب عنوان URL.
تظهر صفحة تسجيل الدخول إلى Oracle Identity Cloud Service.
يقوم المستخدم بتقديم بيانات اعتماد تسجيل الدخول إلى Oracle Identity Cloud Service.
بعد قيام المستخدم بتسجيل الدخول ، يقوم Oracle Identity Cloud Service بتكوين جلسة عمل للمستخدم وإصدار رمز اعتماد.
يقوم تطبيق الويب باستدعاء الخلفية (أو الخادم إلى الخادم) لاستبدال رمز الاعتماد الخاص بمقطع الوصول.
يُصدر Oracle Identity Cloud Service مقطع وصول ومقطع معرف.
يتم إنشاء جلسة عمل ، وتتم إعادة توجيه المستخدم إلى الصفحة الرئيسية .
تظهر الصفحة الرئيسية لتطبيق الويب.

حالة الاستخدام #2: الحصول على تفاصيل حول المستخدم

وصف الشكل التوضيحي get-details-user.png

يحدث تدفق البيانات بهذه الطريقة:

يطلب المستخدم مورد /myProfile.
يستخدم تطبيق الويب SDK الخاص بـ Oracle Identity Cloud Service لمراجعة مقطع المعرف.
تشتمل البيانات التي يتم إرجاعها من تدقيق مقطع المعرف على بيانات المستخدم بصيغة كائن JSON.
تقدم صفحة مرجعي كائن JSON كمحتوى HTML.

تعرف على الطرق والوظائف

Java SDK هو ملف JAR الذي تقوم بتحميله كمكتبة تطبيق ويب. يتطلب ملف JAR هذا مكتبات الطرف الثالث هذه والتي يجب تحميلها كذلك إلى المكتبة:

يشتمل ملف Java SDK المضغوط على مكتبات الجهات الخارجية المطلوبة التالية لـ SDK. يمكنك تحميلها إلى التطبيق.

برنامج ASM Helper Minidev 1.0.2
Apache Commons Collections 4.1
Apache Commons Lang 3.7
JSON صغير ومحلل سريع 2.3
Nimbus LangTag 1.4.3
نيمبا JOSE+JWT 5.14
OAuth 2.0 SDK باستخدام OpenID Connect Extensions 5.30

يوفر Oracle عينة لتطبيق ويب Java لتوضيح كيفية استخدام Java SDK. تم إنشاء هذا التطبيق باستخدام تقنية Servlet لتبسيط خبرة التعلم لفهم كيفية عمل Java SDK. يستخدم التطبيق "Maven" للحصول على كل المكتبات وإنشاء ملف مورد تطبيق ويب (WAR).

يتطلب Java SDK طبعة كائن HashMap تم تحميلها باستخدام معلومات اتصال Oracle Identity Cloud Service. يقوم تطبيق ويب Java بتنفيذ طبعة HashMap هذه كسمة طبقة في طبقة ConnectionOptions.java.

//Instance of a HashMap.
    private Map<String,Object> options = new HashMap<>();
  
public ConnectionOptions(){
        this.options = new HashMap<>();
}
  
public Map<String,Object> getOptions(){
        //Adding Oracle Identity Cloud Service connection parameters to the HashMap instance.
        this.options.put(IDCSTokenAssertionConfiguration.IDCS_HOST, "identity.oraclecloud.com");
        this.options.put(IDCSTokenAssertionConfiguration.IDCS_PORT, "443");
        this.options.put(IDCSTokenAssertionConfiguration.IDCS_CLIENT_ID, "123456789abcdefghij");
        this.options.put(IDCSTokenAssertionConfiguration.IDCS_CLIENT_SECRET, "abcde-12345-zyxvu-98765-qwerty");
        this.options.put(IDCSTokenAssertionConfiguration.IDCS_CLIENT_TENANT, "idcs-abcd1234");
        this.options.put(Constants.AUDIENCE_SERVICE_URL, "https://idcs-abcd1234.identity.oraclecloud.com");
        this.options.put(Constants.TOKEN_ISSUER, "https://identity.oraclecloud.com/");
        this.options.put(Constants.TOKEN_CLAIM_SCOPE, "urn:opc:idm:t.user.me openid");
        this.options.put("SSLEnabled", "true");
        this.options.put("redirectURL", "http://localhost:8080/callback");
        this.options.put("logoutSufix", "/oauth2/v1/userlogout");
        this.options.put(Constants.CONSOLE_LOG, "True");
        this.options.put(Constants.LOG_LEVEL, "DEBUG");
        return this.options;
    }

فيما يلي شرح مختصر لكل سمة مطلوبة لـ SDK:

الاسم	البيان
`IDCSTokenAssertionConfiguration.IDCS_HOST`	لاحقة النطاق لطبعة Oracle Identity Cloud Service.
`IDCSTokenAssertionConfiguration.IDCS_PORT`	رقم منفذ HTTPS الذي تم حجزه لطبعة Oracle Identity Cloud Service (عادة ما يكون 443).
`IDCSTokenAssertionConfiguration.IDCS_CLIENT_ID`	قيمة معرف العميل التي يتم إنشاؤها بعد تسجيل تطبيق ويب Java في وحدة تحكم Identity Cloud Service.
`IDCSTokenAssertionConfiguration.IDCS_CLIENT_SECRET`	قيمة كلمة سر العميل التي يتم إنشاؤها بعد تسجيل تطبيق ويب Java في وحدة تحكم Identity Cloud Service.
`IDCSTokenAssertionConfiguration.IDCS_CLIENT_TENANT`	بادئة النطاق لطبعة Oracle Identity Cloud Service. وهذه البادئة عادة ما تكون قيمة مشابهة لـ `idcs-abcd1234`.
`Constants.AUDIENCE_SERVICE_URL`	عنوان URL لاسم النطاق المؤهل بالكامل لطبعة Oracle Identity Cloud Service.
`Constants.TOKEN_ISSUER`	بالنسبة لهذه السمة ، توصي Oracle بالاحتفاظ بالقيمة `https://identity.oraclecloud.com`.
`Constants.TOKEN_CLAIM_SCOPE`	يتحكم المجال في البيانات التي يمكن للتطبيق الوصول إليها أو معالجتها نيابة عن مستخدم Oracle Identity Cloud Service. إذا استخدم التطبيق SDK لتصديق مستخدم ، يكون المجال هو `openid`. إذا كان التطبيق يستخدم SDK للحصول على تفاصيل حول المستخدم ، فإن المجال هو `urn:opc:idm:t.user.me openid`.
`SSLEnabled`	يشير إلى ما إذا كانت استجابة Oracle Identity Cloud Service لطلبات HTTPS أو HTTP. بالنسبة لهذه السمة ، توصي Oracle بالاحتفاظ بالقيمة `true`.
`Constants.CONSOLE_LOG`	تمكين سجل SDK.
`Constants.LOG_LEVEL`	للإشارة إلى مستوى تسجيل SDK.

يستخدم التطبيق كلاً من سمتي logoutSufix و redirectURL لتجنب التعليمات البرمجية الدائمة لهذه القيم. لا تتطلب SDK أي منها.

يقوم تطبيق ويب Java بتنفيذ طبقة AuthServlet، والتي تقوم بتعيين عنوان URL لـ /auth. عندما يقرر المستخدم التصديق مع Oracle Identity Cloud Service، يقوم متصفح الويب بعمل طلب إلى عنوان URL هذا. تقوم كلاس AuthServlet بتهيئة كائن Authentication Manager، باستخدام Java SDK لإنشاء عنوان URL لرمز اعتماد Oracle Identity Cloud Service، ثم إعادة توجيه متصفح الويب إلى عنوان URL هذا.

public class AuthServlet extends HttpServlet {
    protected void processRequest(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        //Loading the configurations
        Map<String, Object> options = new ConnectionOptions().getOptions();
        //Configuration object instance with the parameters loaded.
        IDCSTokenAssertionConfiguration config = new IDCSTokenAssertionConfiguration(options);
	String redirectUrl = (String)options.get("redirectURL");
        String scope = (String)options.get(Constants.TOKEN_CLAIM_SCOPE);
        //Authentication Manager loaded with the configurations.
        AuthenticationManager am = AuthenticationManagerFactory.getInstance(config);
        //Using Authentication Manager to generate the Authorization Code URL, passing the
        //application's callback URL as parameter, along with code value and code parameter.
        String authzURL = am.getAuthorizationCodeUrl(redirectUrl, scope, "1234", "code");
        //Redirecting the browser to the Oracle Identity Cloud Service Authorization URL.
        response.sendRedirect(authzURL);
    }
}

تستخدم المعاملات التالية لتكوين URL رمز الصلاحية:

الاسم	البيان
`redirectUrl`	بعد قيام المستخدم بتسجيل الدخول ، يقوم Oracle Identity Cloud Service بإعادة توجيه مستعرض الويب الخاص بالمستخدم إلى عنوان URL هذا. يجب أن يتطابق عنوان URL هذا مع العنوان الذي ستقوم بتكوينه للتطبيق الموثوق به في وحدة تحكم Identity Cloud Service. يرجى الاطلاع على تسجيل تطبيق Java لمزيد من المعلومات حول تحديد عنوان URL لإعادة التوجيه لتطبيق ويب Java.
`scope`	مجال OAuth أو OpenID Connect الخاص بالتصديق. يتطلب هذا التطبيق تصديق `openid` فقط.
`state`	يقوم بروتوكول OAuth بتعريف هذه المعلمة. يستخدم عينة تطبيق ويب Java هذه التعليمات البرمجية للتحقق من إمكانية إنشاء اتصال بـ Oracle Identity Cloud Service. على سبيل المثال ، قيمة هذه المعلمة هي `1234`.
`response_type`	المعامل المطلوب بواسطة نوع منح رمز الصلاحية. على سبيل المثال ، قيمة هذه المعلمة هي `code`.

بعد قيام المستخدم بتسجيل الدخول ، يقوم Oracle Identity Cloud Service بإعادة توجيه مستعرض الويب الخاص بالمستخدم إلى عنوان URL للاستدعاء ، والذي يجب على المطور تنفيذه. يستخدم تطبيق الويب Java التطبيق CallbackServlet لمعالجة هذا الطلب.

public class CallbackServlet extends HttpServlet {
    protected void processRequest(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        //Loading the configurations
        Map<String, Object> options = new ConnectionOptions().getOptions();
        //After Oracle Identity Cloud Service authenticates the user, the browser is redirected to the
        //callback URL, implemented as a Servlet.
        IDCSTokenAssertionConfiguration config = new IDCSTokenAssertionConfiguration(options);
        //Authentication Manager loaded with the configurations.
        AuthenticationManager am = AuthenticationManagerFactory.getInstance(config);
        //Getting the authorization code from the "code" parameter
        String authzCode = request.getParameter("code");
        //Using the Authentication Manager to exchange the Authorization Code to an Access Token.
        AuthenticationResult ar = am.authorizationCode(authzCode);
        //Getting the Access Token object and its String value.
        AccessToken access_token = ar.getToken(OAuthToken.TokenType.ACCESS_TOKEN);
        String access_token_string = access_token.getToken();
        //Getting the ID Token object and its String value.
        IdToken id_token = ar.getToken(OAuthToken.TokenType.ID_TOKEN);
        String id_token_string = id_token.getToken();
        //Validating both Tokens to acquire information for User such as UserID, 
        //DisplayName, list of groups and AppRoles assigned to the user.
        IdToken id_token_validated = am.validateIdToken(id_token_string);
        //Storing information into the HTTP Session.
        HttpSession session=request.getSession();
        session.setAttribute("access_token", access_token_string);
        session.setAttribute("id_token", id_token_string);
        session.setAttribute("userId", id_token_validated.getUserId());
        session.setAttribute("displayName", id_token_validated.getDisplayName());
	//Forwarding the request to the Home page.
        request.getRequestDispatcher("private/home.jsp").forward(request, response);
    }
}

يطلب التطبيق معامل رمز الاعتماد واستخدامه لاستدعاء طريقة AuthenticationManager.authorizationCode() الخاصة بـ Java SDK لطلب كل من مقطع الوصول ومقطع المعرف. يستخدم بريمج الخادم بعد ذلك طبعة AuthenticationManager لتدقيق مقطع المعرف. ترجع أساليب AuthenticationManager.validateIdToken() طبعة من كائن IdToken الذي يشتمل على معلومات المستخدم مثل اسم العرض ، ومعرف المستخدم ، وقائمة المجموعات وأدوار التطبيق المعينة للمستخدم. يتم تخزين بعض قيم مقطع الوصول ومقطع المعرف ، وبعض معلومات المستخدم في كائن جلسة عمل HTTP حتى يمكن توجيه الطلب إلى عنوان URL محمي داخل التطبيق الذي يسمى /private/home.jsp. بالإضافة إلى /private/home.jsp، فإن تطبيق ويب Java يشتمل على URLs محمي آخر: /private/myProfile.jsp.

تستخدم صفحة myProfile.jsp عينة التعليمات البرمجية التالية للحصول على مزيد من المعلومات حول المستخدم الذي قام بتسجيل الدخول إلى Oracle Identity Cloud Service:


<%if(session.getAttribute("access_token")==null) response.sendRedirect("/login.html");%>
<!DOCTYPE html>
<%
/**
 * The /private/myProfile.jsp page accesses the user's access token previously set in the session, 
 * calls the getAuthenticatedUser method to retrieve the user's information, and then formats it as HTML.
 * @author felippe.oliveira@oracle.com
 * @Copyright Oracle
*/
  java.util.Map<String, Object> options = new sampleapp.util.ConnectionOptions().getOptions();
  //Configuration object instance with the parameters loaded.
  oracle.security.jps.idcsbinding.shared.IDCSTokenAssertionConfiguration configuration = new oracle.security.jps.idcsbinding.shared.IDCSTokenAssertionConfiguration(options);
  oracle.security.jps.idcsbinding.shared.AuthenticationManager am = oracle.security.jps.idcsbinding.shared.AuthenticationManagerFactory.getInstance(configuration);
  
  //Getting the Access Token and the Id Token from the session object
  String access_token_string = (String)session.getAttribute("access_token");
  String id_token_string = (String)session.getAttribute("id_token");

  //Validating the ID Token to get user information, groups and app roles associated with the user.
  oracle.security.jps.idcsbinding.api.AccessToken access_token_validated = am.validateAccessToken(access_token_string);
  oracle.security.jps.idcsbinding.api.IdToken id_token_validated = am.validateIdToken(id_token_string);
%>

تعمل صفحة /private/myProfile.jsp على الوصول إلى قيمة مقطع المعرف التي تم تعيينها في جلسة العمل ، واستدعاء أسلوب AuthenticationManager.validateIdToken() لاسترجاع معلومات المستخدم ، ثم تقديمها كمحتوى HTML.


<p><b>Information from the Identity Token:</b></p><p><%
out.println("DisplayName = "+ id_token_validated.getDisplayName() +"<br>");
out.println("IdentityDomain = "+ id_token_validated.getIdentityDomain() +"<br>");
out.println("UserName = "+ id_token_validated.getUserName()+"<br>");
out.println("UserId = "+ id_token_validated.getUserId()+"<br>");
out.println("Issuer = "+ id_token_validated.getIssuer()+"<br>");

java.util.List<oracle.security.jps.idcsbinding.api.IDCSAppRole> appRoles = id_token_validated.getAppRoles();
if(!appRoles.isEmpty()){
   out.println("App Roles:<br>");
   for(oracle.security.jps.idcsbinding.api.IDCSAppRole appRole: appRoles){
      out.println("&nbsp;appRole = "+ appRole.getName() +"<br>");
   }//for
}//if

java.util.List<oracle.security.jps.idcsbinding.api.IDCSGroup> groups = id_token_validated.getGroupMembership();
if(!groups.isEmpty()){
   out.println("Groups:<br>");
   for(oracle.security.jps.idcsbinding.api.IDCSGroup group: groups){
      out.println("&nbsp;group = "+ group.getName() +"<br>");
   }//for
}//if
%>
</p>
<p><b>Access Token:</b></p><p><%=access_token_string%></p>

لتوقيع المستخدم من الدخول الموحد بين التطبيق و Oracle Identity Cloud Service ، يقوم تطبيق ويب Java بتنفيذ LogoutServlet الذي يقوم بتخطيط عنوان URL لـ /logout:

public class LogoutServlet extends HttpServlet {
    protected void processRequest(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        HttpSession session=request.getSession();
        String id_token = (String)session.getAttribute("id_token");
        session.invalidate();
        Map options = new ConnectionOptions().getOptions();
        String logoutURL = (String)options.get(Constants.AUDIENCE_SERVICE_URL) + (String)options.get("logoutSufix") +"?post_logout_redirect_uri=http%3A//localhost%3A8080&id_token_hint="+ id_token;
        response.sendRedirect(logoutURL);
    }
}

يقوم بريمج الخادم هذا بإلغاء صلاحية جلسة عمل التطبيق ، ثم يقوم بإعادة توجيه متصفح ويب المستخدم إلى عنوان URL للخروج من OAuth الخاص بـ Oracle Identity Cloud Service.