Develop a Java Application with Oracle Identity Cloud Service

Understand the authentication flow and learn how the example Customer Quotes application implements the integration with Oracle Identity Cloud Service using Java servlets.

Understand the Authentication Flow

The following process flow describes the steps in the authentication flow and the communication between an example Customer Quotes application and Oracle Identity Cloud Service.

The user accesses the Customer Quotes application (https://localhost:8181/cquotes), and then clicks Login with Identity Cloud Service.
The Customer Quotes application prepares an authorization code request in the following format:
- URL: https://example.identity.oraclecloud.com/oauth2/v1/authorize?client_id=clientid&response_type=code&redirect_uri=https://localhost:8181/cquotes/return&scope=openid
- Parameters:
  - client_id: The Customer Quotes unique Application ID that is registered in Oracle Identity Cloud Service.
  - response_type: The expected response from Oracle Identity Cloud Service. In this step, it is the authorization code.
  - redirect_uri: The URL where the authorization code is sent after the user completes the authentication and authorization with Oracle Identity Cloud Service.
  - scope: Controls what data the Customer Quotes application can access and process on behalf of the user. Because OpenID Connect is used, the scope is openid.
The Customer Quotes application redirects the user to the Oracle Identity Cloud Service authorization code URL that was generated in Step 2.
Oracle Identity Cloud Service receives the authorization code request from the Customer Quotes application (identified by its client_id).
Oracle Identity Cloud Service verifies whether the user is already authenticated. If so, Oracle Identity Cloud Service skips the sign-in process. If not, Oracle Identity Cloud Service starts the sign-in process and displays the Sign In page.
The user submits the sign-in credentials to Oracle Identity Cloud Service for validation. The Oracle Identity Cloud Service sign-in process applies the password policy until the sign-in credentials are successfully validated.
If the sign-in process is successful, Oracle Identity Cloud Service redirects the user back to the Customer Quotes application by using the following redirect URL:
- URL:
  - https://localhost:8181/cquotes/return?code=code
- Parameter:
  - code: The authorization code that is created by Oracle Identity Cloud Service.
The Customer Quotes application extracts the authorization code from the request.
The Customer Quotes application communicates directly with Oracle Identity Cloud Service to exchange the authorization code for a user access token by using the following URL and headers:
- URL: https://example.identity.oraclecloud.com/oauth2/v1/token?grant_type=authorization_code&code=code
- Request Headers:
  - Authorization=Basic (client_id:client_secret, 64-bit encoded)
  - Accept=*/*
- Parameters:
  - grant_type: Since you're using an authorization_code to request an access token from Oracle Identity Cloud Service, the grant type must be authorization_code.
  - code: The authorization code received from Oracle Identity Cloud Service, after the user signs in successfully.
- Headers List:
  - Authorization: The trusted application client_id and client_secret (64-bit encoded) in the format: client_id:client_secret.
  - Accept: The type of response the Customer Quotes application expects
    .
Oracle Identity Cloud Service validates the request and returns the following JSON Web Token (JWT) to the Customer Quotes application:
- JWT Content:
  - access_token: Contains information about the user. The Customer Quotes application can use this token when making Oracle Identity Cloud Service API calls on behalf of the user. The access_token content depends on the scope that is requested during the authentication process.
  - id_token: The primary token in OpenID Connect and is used to authorize the endpoint with scope=openid. The id_token contains the identification information (for example, name and email) about the user. This information can be used by the client application for several purposes, including verification and displaying content. A legitimate (verified by the client based on an OpenID Connect provider signature) and active id_token tells the application that the user has authenticated and has a valid token.
The Customer Quotes application processes the JWT token (id_token) and then extracts the user information that is returned by Oracle Identity Cloud Service, such as name and email.
The Customer Quotes application displays the home page containing information about the user, such as name and email.

Understand the Java application Code

The example Customer Quotes application uses servlet technology.

The application is composed of the following main servlets:

com.example.servlet.AccessResourceServlet: Initiates the authentication flow by redirecting the user to Oracle Identity Cloud Service to request an authorization code.
com.example.servlet.ReturnServlet: Handles the redirect URL from the Oracle Identity Cloud Service, receives the authorization code, and uses the com.example.utils.OICOAuthClient class to exchange the authorization code for an identity token and an access token.
com.example.servlet.LogoutServlet: Terminates the application's user session, but doesn't sign-out the user from Oracle Identity Cloud Service.

The servlets use the following utility classes:

com.example.utils.OICOAuthClient: Constructs the URL endpoints for Oracle Identity Cloud Service REST API, processes requests, parses Oracle Identity Cloud Service responses, and adds user information to the application's HTTP session.
com.example.utils.HttpUtil: Handles the HTTP communication with Oracle Identity Cloud Service REST API endpoints. All communication directly from the Customer Quotes application to Oracle Identity Cloud Service is made through the java.net.HttpURLConnection class.