Use OAuth 2.0 and Open ID Connect in a Custom Application

Purpose

In this tutorial you learn to configure Federated Single Sign-On (Federated SSO) between Oracle Identity Cloud Service and a custom application using OAuth 2.0 and OpenID Connect.

Time to Complete

90 minutes

Background

Oracle Identity Cloud Service supports the following frameworks for federated SSO and authorization integration with custom applications:

1. OAuth 2.0: Framework for authorization, commonly used for third-party authorization requests with consent. See OAuth for more information.
2. OpenID Connect: Authentication protocol that provides Federated SSO leveraging the OAuth 2.0 authorization framework. See OpenID Connect for more information.

These standards provide the following benefits:

1. Federated SSO between custom applications and Oracle Identity Cloud Service. Resource owners (users accessing the Customer Quotes application) need a single login to access Oracle Identity Cloud Service plus all applications integrated. Oracle Identity Cloud Service handles the authentication and credentials itself, insulating custom applications.
   This capability is provided by OpenID Connect with OAuth 2.0.
2. Authorization to perform operations on third-party servers with consent. Resource owners can decide at runtime whether the application should have authorization to access data or perform tasks for them.
   This capability is provided by OAuth 2.0.

Scope

In this tutorial, you implement Federated SSO between Oracle Identity Cloud Service and Customer Quotes, a sample client application that serves as a hub for sales quotations. The authentication has the following flow:

The Customer Quotes application, after integration:

• Requires just one login from the resource owner to access both Oracle Identity Cloud Service and the custom application.
• Displays information about the resource owner (name and email), provided by Oracle Identity Cloud Service. (Customer Quotes does not store that information).

What Do You Need?

• Experience developing in Java.
• Access to Oracle Identity Cloud Service with authorization to manage applications
  (Identity Domain Administrator, Security Administrator, or Application Administrator).
• Netbeans IDE 8.1 (bundle All or Java EE).
  Tip: To learn more about how to install Netbeans 8.1, visit the official documentation.

• Clone or Download the idm-samples repository on GitHub:

  View idm-samples on GitHub

  Important: The Customer Quotes (sample code) is provided “AS IS” with no express or implied warranty for accuracy or accessibility. The sample code is intended to demonstrate the basic integration between Oracle Identity Cloud Service and custom applications and does not represent, by any means, the recommended approach nor is it intended to be used in development or productions environments.

In this section, you export the SSL certificate from the Oracle Identity Cloud Service UI and import it into Netbeans' Glassfish Server trust store. This step is required for the custom application to communicate with Oracle Identity Cloud Service via https.

Export Certificate from Oracle Identity Cloud Service

1. Launch your browser. (in this tutorial, we are using Google Chrome on Windows)
2. Access the Oracle Identity Cloud Service UI.
3. In the browser address bar, click view website information (locker icon), and then click Details.
4. Click View Certificate.
5. Click Details then click Copy to File
6. Click Next, select Base-64 encoded X.509 (.CER), and then click Next.
7. Save the certificate as oracle.cer in a temporary folder such as D:\temp, click Next and then Finish.
8. Click OK, close the certication pop-up and your browser.

Import Oracle Identity Cloud Service Certificate in Glassfish

1. Launch Netbeans.
2. Click Services, expand Servers, right-click Glassfish Server, and then click Properties.



3. Record the Glassfish domains folder.
Tip: You will import the Identity Cloud Service certificate under this folder.



4. Close Netbeans.
5. Launch a command prompt as administrator.
Tip: in Windows 7, click the start menu, type cmd, right-click the cmd.exe shortcut, click Run as Administrator, and then click Yes.
6. Enter where keytool to confirm that the keytool utility is available from your OS classpath. The prompt should return a message containing the keytool location:

where keytool
C:\Program Files\Java\jdk1.8.0_60\bin\keytool.exe

Tip: If keytool is not available (INFO: Could not find files for the given pattern(s).), export it to the path using the commands below, replacing JAVA_HOME with your JDK location (The file location might be different depending on where you installed the JDK):

set PATH=%PATH%;C:\Program Files\Java\jdk1.8.0_60\bin
where keytool
C:\Program Files\Java\jdk1.8.0_60\bin\keytool.exe

7. Navigate to Netbeans' Glassfish domain folder and run the keytool command (You recorded the domain folder earlier in this tutorial):

cd %GLASSFISH_DOMAIN_FOLDER%\domain1\config
keytool -import -keystore "cacerts.jks" -trustcacerts -file "D:\temp\oracle.cer" -alias idcs -storepass changeit

8. In the confirmation prompt, enter yes.
9. To confirm the import was a success, enter the command:

keytool -list -keystore "cacerts.jks" -alias idcs -storepass changeit

The terminal should display the certificate fingerprint like in the following example:

idcs, Jun 9, 2016, trustedCertEntry,
Certificate fingerprint (SHA1): 81:CC:82:C6:4B:E9:BD:0C:7E:10:30:10:4E:CE:C2:EB:AC:BE:C5:2B

10. Close the command prompt.

In this task, you launch the Customer Quotes application (sample code) in Glassfish, a J2EE Application Server bundled with the Netbeans IDE.

Important Notes:

• Glassfish is typically used by developers to test and debug Java enterprise applications and runs web applications on two ports: 8080 (HTTP) and 8181 (HTTPS).
• Since Oracle Identity Cloud Service integrates with applications only via HTTPS, you will access the application via port 8181.

• Make sure cloned or downloaded the idm-samples repository before starting this section:

  View idm-samples on GitHub

1. Access Netbeans and click File > Open Project.
2. Navigate to the folder where you cloned the idm-samples repository. Select the cquotes folder, and then click Open Project.
3. To select a specific browser to use, select cquotes, click the browser button in the toolbar, and then select the browser that you want to use.

   

4. Right-click cquotes, and then click Run.
Tip: If prompted for Select Deployment Server, select GlassFish and continue.
5. If the GlassFish Administrator Credentials window appears, enter admin as User, and then click OK.
   Tip: Netbeans requests the administative password to run the Glassfish server. By default, the Password field is blank.

   

   Netbeans deploys the cquotes application in Glassfish. After it finishes, your browser displays the cquotes application (http://localhost:8080/cquotes).
6. Access the following URL: https://localhost:8181/cquotes/.
7. Accept the certificate exception in your browser.
   Tip: To accept a certificate exception in Google Chrome, click Advanced > Proceed to localhost (unsafe).
   The Customer Quotes application appears using the HTTPS address.
   

   

At this point, you are running cquotes on your own machine under the HTTPS address: https://localhost:8181/cquotes/.
In the next steps, you integrate this application with Oracle Identity Cloud Service.

In this task, you configure and activate the Customer Quotes application in Oracle Identity Cloud Service.
During configuration, you define how Oracle Identity Cloud Service integrates with your application.

1. In the Identity Cloud Service console, expand the Navigation Drawer , click Applications, and then click Add.

2. Select Confidential Application.

   Tip: Trusted Applications, differently from a Mobile or Single Page Application, are hosted in a secure place (server). Since you know where this application is hosted, you can trust this application. The UI provides information about each type of application supported by Oracle Identity Cloud Service.

3. Enter Customer Quotes as the Name, Web application that works as a hub for all of your quotations. Access quotes and insights from customers from your browser as the Description, and then click Next.

4. Select Configure this application as a client now.

5. Click Configure this application as a client now, select Authorization Code as Allowed Grant Types, and enter the information according to the table, and then click Next.

   Application wizard - Values for the Authorization page

   Attribute	Value	Description
   Redirect URL	https://localhost:8181/cquotes/return	URL where users will be redirected to cquotes after authentication/authorization in Oracle Identity Cloud Service
   Logout URL	https://localhost:8181/cquotes/logout	URL that should be called by Oracle Identity Cloud Service during the logout process. When this URL is called, the resource owner session is terminated in Customer Quotes.
   Post Logout Redirect URL	https://otn.oracle.com	URL where the resource owner should be redirected after the Oracle Identity Cloud Service logout.

6. Click Next in the following panes until you reach the last pane. Then click Finish.

7. Save the Client ID and the Client Secret, and then click Close.

   

   Tip: The Client ID and Client Secret are equivalent to a credential (ID and password) that your application uses to communicate with Oracle Identity Cloud Service.
8. Click Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

At this point, you have an application entry with a client ID and a client secret for integrating your application with Oracle Identity Cloud Service. In the next steps, you integrate your application with Oracle Identity Cloud Service.

In this task, you configure the Customer Quotes application to connect with Oracle Identity Cloud Service during authentication.

1. Return to Netbeans and open the file cquotes > Source Packages > com.example.utils > ClientConfig.java.
   Tip: The ClientConfig.java file contains settings that the Customer Quotes application uses during runtime to connect to Oracle Identity Cloud Service.

2. Update the CLIENT_ID, CLIENT_SECRET, and IDCS_URL as follows:

Values for ClientConfig.java file

Attribute	Value
CLIENT_ID and CLIENT_SECRET	The values you obtained while creating the Customer Quotes application in Oracle Identity Cloud Service.
IDCS_URL	The Oracle Identity Cloud Service url. For example: https://example.identity.oraclecloud.com.

//YOUR IDENTITY DOMAIN AND APPLICATION CREDENTIALS
public static final String CLIENT_ID = "75508987f27b42e08dc14f6c3cee8a96";
public static final String CLIENT_SECRET = "b522d6cb-67fd-4bb6-92d2-b0f3d212be40";
public static final String IDCS_URL = "https://example.identity.oraclecloud.com";

3. Save the ClientConfig.java file.

1. Return to your browser and make sure that you are not logged in to Oracle Identity Cloud Service.
2. In Netbeans, right-click cquotes, and then click Run. Your web browser displays the Customer Quotes application.
3. Access https://localhost:8181/cquotes/ (to launch the Customer Quotes application in HTTPS).
4. Click Login with Identity Cloud Service.

   

5. Authenticate with your credentials.

   

6. After a successful authentication, Oracle Identity Cloud Service redirects you back to the Customer Quotes application, which displays a welcome message.

   

7. In the upper-right corner, expand the menu and then click My Profile.

   

   A new window displays your profile information in Oracle Identity Cloud Service.

   

   This indicates that the Federated SSO between Oracle Identity Cloud service and your application works.
8. Return to the Customer Quotes window, expand the upper-right corner menu and then click Logout. You should be redirected to the Oracle Technology Network website.
9. Access https://localhost:8181/cquotes/, and then Oracle Identity Cloud Service. You should not be recognized as a logged-in user in both places. This indicates that the logout worked.

In the last task, you executed Federated SSO between Oracle Identity Cloud Service and the Customer Quotes application leveraging OpenID Connect with OAuth 2.0. The authentication was executed through the following process:

The authentication steps:

1. The resource owner accesses the Customer Quotes application (https://localhost:8181/cquotes), and then clicks Login with Identity Cloud Service.
2. The Customer Quotes application prepares an authorization code request URL using the following format:
   

   https://example.identity.oraclecloud.com/oauth2/v1/authorize?client_id=clientid&response_type=code&redirect_uri=https://localhost:8181/cquotes/return&scope=openid

Authorization Code request attributes

Attribute	Sample Value	Description
client_id	2e1a31df02a234e0bd8c18d396c47647	The Customer Quotes unique Application ID (client_id) registered in Oracle Identity Cloud Service.
response_type	code	The expected response from Oracle Identity Cloud Service. In this step, it is the authorization code.
redirect_uri	https://localhost:8181/cquotes/return	The URL where the authorization code should be sent after the resource owner completes authentication/authorization with Oracle Identity Cloud Service.
scope	openid	Scope contols what data the Customer Quotes application can access/process on behalf of the resource owner. Because we are using OpenID Connect, we requestopenid as the scope.

3. The Customer Quotes application redirects the resource owner to the authorization code URL.
4. Oracle Identity Cloud Service receives the authorization code request and identifies that the Customer Quotes application (identified by its client_id) is requesting an authorization code to get more information about the resource owner (scope openid).
5. Oracle Identity Cloud Service checks whether the resource owner is authenticated. If not, it presents the login page.
6. The resource owner submits the credentials to Oracle Identity Cloud Service.
7. Oracle Identity Cloud Service checks the resource owner credentials. If the login is successful, Oracle Identity Cloud Service prepares a response to the Customer Quotes application using the following format:
   

   https://localhost:8181/cquotes/return?code=code

Authorization Code response url and attributes

Attribute	Sample Value	Description
url	https://localhost:8181/cquotes/return	The URL where the authorization code should be sent to the Customer Quotes application
code	DUllQVElPTl9LRVkxNCB7djF9NCA=	The authorization code created by Oracle Identity Cloud Service

8. Oracle Identity Cloud Service redirects the resource owner back to the Customer Quotes application.
9. The Customer Quotes application extracts the authorization code from the resource owner request.
10. The Customer Quotes application requests an access token from Oracle Identity Cloud Service using the following URL and headers:
    

    https://example.identity.oraclecloud.com/oauth2/v1/token?grant_type=authorization_code&code=code

    Access Token request attributes

    Attribute	Sample Value	Description
    grant_type	authorization_code	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	DUllQVElPTl9LRVkxNCB7djF9NCA=	The authorization code received from Oracle Identity Cloud Service when the resource owner returns from authentication.

    Headers and parameters:

    Authorization=Basic (client_id:client_secret 64bit encoded)
    Accept=*/*

    Access Token request headers

    Header	Sample Value	Description
    Authorization	Basic Y29udHJhdHVsYXRpb25zeW91Zm91bmRhbmVhc3RlcmVnZzppbnNpZGV0aGlzdHV0b3JpYWwK	The Customer 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.

11. Oracle Identity Cloud Service validates the request and returns the following tokens to the Customer Quotes application:

Return from the access token request

Token	Description
access_token	The access token contains information about which scopes the Customer Quotes application can request on behalf of the resource owner. The Customer Quotes application can use this token when making API calls on behalf of the resource owner.
id_token	This is a special token that is retrieved only when you request the scope openid. The id_token contains the identification information (for example, email and name) about the resource owner. This information is used for the federated authentication.

The Oracle Identity Cloud Service tokens are in JSON Web Token (JWT) format. See JWT for more information on JSON Web Tokens.

12. The Customer Quotes application processes the id_token JWT token, and then extracts the resource owner information returned by Oracle Identity Cloud Service, such as name and email.
13. The Customer Quotes application displays the home page containing information about the resource owner, such as name and email.

In this task, you can make Oracle Identity Cloud Service to display the Customer Quotes application under My Apps page for specific users.

1. In the Identity Cloud Service console, expand the Navigation Drawer , click Applications, and then click Customer Quotes.
2. Update the fields as follows and click Save.

Values for the Application page

Attribute	Value
Application Icon	Upload the image provided with cquotes sample code under cquotes/icon.gif
Application URL	https://localhost:8181/cquotes
Display in My Apps	selected



Important: During the update, Identity Cloud Service may display the error 'Cannot update application Customer Quotes. An App with a LoginTarget that specifies 'OIDC' as its loginMechanism must have the OAuthResource facet enabled.'. If so, check the section "A Trusted Application With "No Resources" Defined Doesn't Display in the My Apps Page" available in the Oracle Cloud Known Issues for Oracle Identity Cloud Service guide.

3. Under Users, click the particular user that you want to assign access to the application, click Access.
4. Click Assign, Search and select users that will have the Customer Quotes application displayed under My Apps, and then click OK.



Tip: Users assigned in this page will have the Customer Quotes application exposed under My Apps:

To learn more about how to use the REST APIs for Federated SSO (using OpenID Connect plus OAuth 2.0) and Authorization scenarios (using OAuth 2.0), explore the following tutorials:

• Integrating a Custom Resource Server Application

To learn more about the REST APIs, explore the following tutorials and documents:

• Oracle Identity Cloud Service: REST API documentation

• Oracle Identity Cloud Service: First REST API Call

• Oracle Identity Cloud Service: Managing Users Using REST API Calls

• Oracle Identity Cloud Service: Managing Groups Using REST API Calls

• Developer(s): Frederico Hakamine.
• Contributor(s): Andressa Silva, Paulo Albuquerque, and Vinicius Hakamine.