Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Java Web Applications

Before You Begin

This 15 minutes tutorial shows you how to use Oracle Identity Cloud Service's Software Development Kit (SDK) for the Java programming language to enable a sample web application to authenticate with Oracle Identity Cloud Service.

Series

This is a tutorial in the Use Oracle Identity Cloud Service's Software Development Kit (SDK) series. Read them in any order.

• Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Java Web Applications
• Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Node.js Web Applications
• Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Python Web Applications
• Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in .NET Web Applications

Background

Oracle Identity Cloud Service provides a Software Development Kit (SDK) that you download from the console, and you can use to integrate Java web applications with Oracle Identity Cloud Service.

The Java SDK is available as a Java Archive (JAR) (idcs-assert.jar) file, which must be loaded as a web application library.

To help you understand how to use the SDK, this tutorial uses a sample web application as a reference.

Important: The sample web application isn't meant to be published to production and isn't concerned about the language’s specific best practices, such as data handling, patterns, security, and so on. The sole purpose of the sample web application is to address the recommended approach to integrate Oracle Identity Cloud Service and a custom application using the SDK.

What Do You Need?

• A basic knowledge of the Java programming language to understand the code logic presented in this tutorial.
• To install the Java SDK 8
• To install Netbeans IDE 8.2 (All or Java EE bundle) with Maven plugin installed.
• To download the Java sample web application as zip file, and to extract its content to the c:\temp folder of your desktop.
• The sample application is built with Maven which automatically downloads the appropriate libraries and builds the war file. Below is the list of libraries the SDK needs:
  
  • ASM Helper Minidev 1.0.2
  • Apache Commons Collections 4.1
  • Apache Commons Lang 3.7
  • JSON Small And Fast Parser 2.3
  • Nimbus LangTag 1.4.3
  • Nimbus JOSE+JWT 5.14
  • OAuth 2.0 SDK With OpenID Connect Extensions 5.30

  Note: The Java SDK zip file contains the correct version of the required third-party libraries necessary for the SDK. You can load them into your application.

• Access to an instance of Oracle Identity Cloud Service, and rights to download the SDK from the console and to add a confidential application

Download the SDK in the Sample Web Application

1. In the Identity Cloud Service console, expand the Navigation Drawer , click Settings, and then click Downloads. The list of files to download appears.
2. Click Download to download the Identity Cloud Service SDK for Java SDK zip file, and save the zip file.
3. Open the java SDK zip file, find the idcs-assert.jar file and extract the jar file into the sample web application library folder (c:\temp\java\src\main\webapp\WEB-INF\lib). The source code structure of the sample web application must be similar to the one below.

   c:\temp\java\
   	    src\
        	       main\
                     java\
                     webapp\
   		   	css\
   		   	...
   	     	   	WEB-INF\
   			  	lib\
   		              	   idcs-assert.jar
        	       test\

   Note: You may need to create the lib folder before copying the file.

   Note: The name of the java sdk jar file may vary. Make note of the current jar file name you downloaded from the Oracle Identity Cloud Service console: .

Register the Sample Web Application with Oracle Identity Cloud Service

The sample web application needs a Client ID and Secret to establish communication with Oracle Identity Cloud Service. You also need to configure API permissions that must be granted to the sample web application. This section explains how to register the sample web application with Oracle Identity Cloud Service.

1. In the Identity Cloud Service console, expand the Navigation Drawer , click Applications.
2. In the Applications page, click Add.

   

3. In the Add Application chooser dialog, click Confidential Application.
4. Populate the Details pane as follows, and then click Next.
   • Name: SDK Web Application
   • Description: SDK Web Application
5. In the Client pane, select Configure this application as a client now, and then populate the fields of this pane, as follows:
   • Allowed Grant Types: Select Client Credentials and Authorization Code.
   • Allow non-HTTPS URLs: Select this check box. The sample application works in non-HTTPS mode.
   • Redirect URL: http://localhost:8080/callback
   • Post Logout Redirect URL: http://localhost:8080
6. In the Client pane, scroll down, click the Add button below Grant the client access to Identity Cloud Service Admin APIs.

   

7. In the Add App Role dialog window, select Authenticator Client and Me in the list, and then click Add.
8. Click Next in the Client pane and in the following panes until you reach the last pane. Then click Finish.
9. In the Application Added dialog box, make a note of the Client ID and Client Secret values, and then click Close.

   

10. To activate the application, click Activate.
11. In the Activate Application? dialog box, click Activate Application.

    The success message The SDK Web Application application has been activated. appears.

12. In the Identity Cloud Service console, click the user name at the top-right of the screen, and click Sign Out.

Update the Sample Web Application

In this section, you update the sample application code to make it use Oracle Identity Cloud Service's SDK for Java programming language.

1. Populate the values of the Client ID , Client Secret , Oracle Identity Cloud Service's tenant and domain suffix .

   As an example, if your Oracle Identity Cloud Service console URL is https://idcs-abcd1234.identity.oraclecloud.com/ui/v1/adminconsole, then idcs-abcd1234 is the tenant value, and identity.oraclecloud.com is the domain suffix value.

   Note: It is important to update the fields above accordingly before continuing to the next steps sections.

2. Edit the c:\temp\java\pom.xml file, locate the following entry, and update the name of the jar file as follows:

           <!-- Replace the name of the Oracle Identity Cloud Service SDK jar file -->
           <dependency>
                   <groupId>oracle.security.jps.idcsbinding</groupId>
                   <artifactId>sdk</artifactId>
                   <version>1.0</version>
                   <scope>system</scope>
                   <systemPath>${basedir}/src/main/webapp/WEB-INF/lib/</systemPath>
           </dependency>
                   

3. Edit the c:\temp\java\src\main\java\sampleapp\util\ConnectionOptions.java file, update the getOptions method with the following content, and then save the file.
   

   public Map<String,Object> getOptions(){
           //Adding Oracle Identity Cloud Service connection parameters to the HashMap instance.
           this.options.put(IDCSTokenAssertionConfiguration.IDCS_HOST, "");
           this.options.put(IDCSTokenAssertionConfiguration.IDCS_PORT, "443");
           this.options.put(IDCSTokenAssertionConfiguration.IDCS_CLIENT_ID, "");
           this.options.put(IDCSTokenAssertionConfiguration.IDCS_CLIENT_SECRET, "");
           this.options.put(IDCSTokenAssertionConfiguration.IDCS_CLIENT_TENANT, "");
           this.options.put(Constants.AUDIENCE_SERVICE_URL, "https://.");
           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.LOG_LEVEL, "INFO");
           this.options.put(Constants.CONSOLE_LOG, "True");
   	return this.options;
   }
   

Run the Sample Web Application

In this section of the tutorial, you prepare, run, and test the sample web application.

1. Launch NetBeans.
2. Click File, and then click Open Project.
3. In the Open Project dialog, select the C:\temp\java folder, and then click Open Project.
4. Right-click the name of the project, and the click Build.

   

   The message BUILD SUCCESS appears at the Output panel of NetBeans.

   Note: The first time you build the project NetBeans downloads the libraries defined in the pom.xml file of the sample application. Make sure you are not behing of a proxy server that avoids Netbeans to access the internet.

   Note: Make sure to copy the Java SDK to the sample web application library folder before building the project. See Download the SDK in the Sample Web Application.

5. Right-click the name of the project, and then click Run.

   

   The sample application uses NetBeans' default port (8080). Make sure your NetBeans is configured to use this same port.

6. A new browser window automatically opens the http://localhost:8080 URL. Then click Log in.
7. In the Login page, click the Oracle red icon.

   

8. In the Oracle Identity Cloud Service Sign In page, sign in using your Oracle Identity Cloud Service credentials.

   After you sign in to Oracle Identity Cloud Service successfully, the browser is redirected to the /home page. The name of the logged-in user appears at the top-right side of the page.

9. In the left menu, click My Profile.
10. Verify that information associated with your profile appears in the center of the page.

    

11. Click Log Out on the upper-right corner. The sample application finalizes the user session and redirects the browser to Oracle Identity Cloud Service's logout URL.

After Oracle Identity Cloud Service logs the user off, it redirects the user browser to the sample application index page. This behavior happens because the sample application adds two parameters post_logout_redirect_uri and id_token_hint to the Oracle Identity Cloud Service logout URL, as per below:

https://./oauth2/v1/userlogout?post_logout_redirect_uri=http%3A//localhost%3A8080&id_token_hint=<ID_TOKEN>

The post_logout_redirect_uri parameter value must match the Post Logout Redirect URL parameter value you set during Register the Sample Web Application with Oracle Identity Cloud Service

Want to Learn More?

• Configure Federated Single Sign-On (Federated SSO) between Oracle Identity Cloud Service and a custom application using OAuth 2.0 and OpenID Connect.
• Administering Oracle Identity Cloud Service guide: Use Case: Adding Applications