Use OAuth 2.0 in a Custom Resource Server Application

Purpose

In this tutorial, you learn to integrate Oracle Identity Cloud Service with a custom resource server application using OAuth 2.0.

Time to Complete

90 minutes

Background

Oracle Identity Cloud Service supports the following frameworks for Federated Single Sign-On (SSO) and authorization integration with custom applications:

1. OAuth 2.0: Framework for authorization, commonly used for third-party authorization requests with consent. For more information about OAuth, see the OAuth 2.0 Authorization Framework specification.
2. OpenID Connect: Authentication protocol that provides Federated SSO that leverages the OAuth 2.0 Authorization Framework. See the OpenID Connect Foundation page for more information.

These standards provide benefits such as:

1. Federated SSO between custom applications and Oracle Identity Cloud Service. Resource owners (Users accessing the Customer Quotes application) just need a single login to access all applications integrated with Oracle Identity Cloud Service plus the Oracle Identity Cloud Service UI. Oracle Identity Cloud Service handles the authentication and credentials, 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 be given authorization to access data or perform tasks on their behalf.
   This capability is provided by OAuth 2.0.

Scope

In this tutorial, you integrate Oracle Identity Cloud Service with Sales Insight, a custom resource server application that provides REST API calls for:

• Sales quotes (/quote)
• Sales insight (/insight)
• Sales reports (/report)
• Sales pipeline (/pipeline)

This diagram displays the authorization and access flow to Sales Insight APIs that occurs after you have integrated your application with Oracle Identity Cloud Service:

View Image

The Sales Insight resource server application after integration:

• Requires an access token to perform any REST API call. This access token is obtained by a client application integrated with Oracle Identity Cloud Service.
• Validates the access token signature using the Oracle Identity Cloud Service signing key.
• Validates the access token scope, audience, and expiration time.
• Returns information only when the access token is properly validated.

What Do You Need?

• Experience developing in Java.
• An Oracle Identity Cloud Service user account with Identity Domain Administrator, Security Administrator, or Application Administrator role.
• Complete the Oracle Identity Cloud Service: Integrating a Custom Client Application tutorial.
  Tip: The client application configured in that tutorial (Customer Quotes) is used to request REST APIs on the Sales Insight resource server.

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

  View idm-samples on GitHub

  Important: The Sales Insight (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 task, you launch the Sales Insight sample code in Glassfish, a J2EE Application Server bundled with the NetBeans IDE.

1. Launch NetBeans, and then click File > Open Project.
2. Navigate to the folder where you cloned the idm-samples repository. Select the salesinsight folder, and then click Open Project.
   Tip: You cloned the idm-samples repository from github during the Oracle Identity Cloud Service: Integrating a Custom Client Application tutorial.
3. The salesinsight entry appears under Projects.

   View Image

   

4. Right-click salesinsight, and then click Run.
5. If the GlassFish Administrator Credentials window appears, enter admin as the User, and then click OK.
   Tip: NetBeans requests the administrative password to run the Glassfish server. By default, the password is blank.

   View Image

   

NetBeans deploys the Sales Insight (salesinsight) application on Glassfish.
6. To confirm that Sales Insight is working, access: http://localhost:8080/salesinsight/quote
   The application returns a random list of quotes in html format.

   View Image

   

   Tip: You can see the return information without providing an access token because Sales Insight is not yet protected.
7. Optionally, access other REST APIs, such as:
   • http://localhost:8080/salesinsight/report
   • http://localhost:8080/salesinsight/insight
   • http://localhost:8080/salesinsight/pipeline

At this point, you are running the Sales Insight application on your own machine at this location: http://localhost:8080/salesinsight/
In the next steps, you register this application in Oracle Identity Cloud Service.

In this task, you register and activate the Sales Insight application in Oracle Identity Cloud Service.
During configuration, you define how Oracle Identity Cloud Service integrates with your application.

1. In the Oracle Identity Cloud Service console, expand the Navigation Drawer , click Applications, and then click Add.
2. Select Confidential Application.
3. Enter Sales Insight as the Application Name, Server that provides via REST APIs sales insight for our team as Description, and click Next.
4. Click Configure this application as a client now, select Client Credentials as Allowed Grant Types, and then click Next.
5. Select Configure this application as a resource server now, enter http://localhost:8080/salesinsight/ as the Primary Audience, and then click Add next to Allowed Scopes.

   View Image

   

6. Enter the scopes according to the table.

   View Image

   

   List of scopes to create with the Resource Service application

   Scope	Description	Requires Consent
   quote	Access quotes requiring your action	true
   insight	Explore insight to improve your sales	true
   pipeline	Access your sales pipeline	true
   report	Access your sales reports	true

7. Compare the Allowed Scopes table to the image below, and then click Finish.

   View Image

   

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

   View Image

   

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

At this point, you have prepared the Sales Insight application with Client ID and Client Secret for integrating with Oracle Identity Cloud Service. In the next steps, you integrate your application with Oracle Identity Cloud Service.

In this task, you configure the Sales Insight application to require access tokens and to verify the access token information during a resource owner’s attempt to access Sales Insight.

1. Return to NetBeans, expand Web Pages > WEB-INF, and then open the web.xml file.
2. Uncomment the snippet between the comments <!-- THIS FILTER VALIDATES THE access token FOR ALL REQUESTS TO SALESINSIGHT --> and <!-- END SERVLET FILTER -->, and save the web.xml file:

   View Image

   

   Tip: The snippet above enables an authorization filter for any request to the Sales Insight resource server application. The filter is provided by the AccessTokenValidator class.
3. Open the ResourceServerConfig.java located here: salesinsight > Source Packages > com.example.utils.
   Tip: The ResourceServerConfig.java file contains settings that the Sales Insight application uses during runtime to connect to Oracle Identity Cloud Service.

4. Update the values for CLIENT_ID, CLIENT_SECRET, and the IDCS_URL.

ResourceServerConfig.java file attributes

Attribute	Value
CLIENT_ID and CLIENT_SECRET	The values that you obtained while creating the Sales Insight application in Oracle Identity Cloud Service. View Image
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";

5. Save the ResourceServerConfig.java file.

1. In NetBeans, right-click salesinsight, and then click Run.
2. Select Output > GlassFish Server 4.1.1, and then confirm that the following message appears: Signing Key from IDCS successfully loaded!

   View Image

   

   This indicates that Sales Insight is able to connect to Oracle Identity Cloud Service and can obtain the Signing Key. This key is used to validate access_token signatures.
   Important:
   • If the message Error loading Signing Key from IDCS appears, stop your application, and then review the information that you provided in the previous steps.
   • In case your browser launches the url http://localhost:8080/salesinsight/, ignore the 500 Internal Server error message.
3. Access: http://localhost:8080/salesinsight/quote

Sales Insight returns the message: Error While Validating Token: No access token provided.

4. Access: http://localhost:8080/salesinsight/quote?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Sales Insight returns the message: Error While Validating Token: Invalid JWT serialization: Missing dot delimiter(s).

You have finished integrating Oracle Identity Cloud Service and Sales Insight. Sales Insight does not process API calls unless you send a valid access token that is generated and signed by Oracle Identity Cloud Service.

In the next steps, you configure the Customer Quotes client application to make API calls to Sales Insight.
Note: You integrated Customer Quotes to Oracle Identity Cloud Service while you explored the Oracle Identity Cloud Service: Integrating a Custom Client Application tutorial.

 

Configuring the Customer Quotes Application in Oracle Identity Cloud Service

1. In the Identity Cloud Service console, expand the Navigation Drawer , click Applications, and then click Customer Quotes.
2. Click Configuration, and then expand Client Configuration.
3. In the Accessing APIs from Other Applications section, click Add (next to Allowed Scopes).

   View Image

   

4. The Sales Insight application is listed as an available resource for selection. Click the arrow next to Sales Insight.

   View Image

   

5. The Sales Insight API scopes appear. These are the APIs calls that Customer Quotes can call in Sales Insight. Select all scopes, and then click Add.

   View Image

   

6. The Allowed Scopes table now displays the scopes that Customer Quotes can access from the Sales Insight resource server. Click Save.

   View Image

   

 

Configuring the Customer Quotes Code to Request the Sales Insight APIs

1. Open the cquotes sample code in NetBeans.

   View Image

   

   Important: You ran the Customer Quotes application while you explored the Oracle Identity Cloud Service: Integrating a Custom Client Application tutorial. As a reminder from that tutorial, 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. The sample code does not represent the recommended approach nor is it intended to be used in development or production environments.
2. In the ClientConfig.java file, update the IS_RESOURCE_SERVER_ACTIVE property value to true.

//SCOPES LEVERAGED BY YOUR APPLICATION
public static final boolean IS_RESOURCE_SERVER_ACTIVE = true;

Tip: The Customer Quotes application is pre-configured with a code to request the Sales Insight APIs when the resource server is active.
3. Save the ClientConfig.java file.

1. In your browser, sign out of Oracle Identity Cloud Service.
2. In NetBeans, right-click salesinsight, and then click Run.
3. In your browser, access http://localhost:8080/salesinsight/quote, and then confirm that the following message returns: Error While Validating Token: No access token provided

   View Image

   

4. Return to NetBeans, right-click cquotes, and then click Clean.
5. Right-click cquotes, and then click Run.
6. In your browser, launch Customer Quotes in HTTPS: https://localhost:8181/cquotes/

   View Image

   

7. Click Login with Identity Cloud Service.
8. Authenticate using your credentials.

   View Image

   

   After a successful authentication, Oracle Identity Cloud Service redirects you back to Customer Quotes, which displays five buttons.
   The first four buttons trigger individual calls from the Customer Quotes application to API calls on Sales Insight. The last button triggers all calls from Customer Quotes to Sales Insight with a single click.

   View Image

   

9. Click Urgent Quotes. A consent screen from Oracle Identity Cloud Service appears.

   View Image

   

   Note: The consent message displays the same description that you associated with the quote scope in the Sales Insight application. At this point, you can authorize the Customer Quotes application to access quotes from Sales Insight on your behalf.
10. Click Don't Allow. The Customer Quotes application displays a user_denied error message.

    View Image

    

11. Click Go back home.
12. Click Urgent Quotes again. This time, click Allow on the consent page. The Customer Quotes page displays a list of quotes that were retrieved from Sales Insight. This indicates that the integration is fully functional.

    View Image

    

13. Optionally, explore the other options within in the Customer Quotes page.
14. Sign out of Customer Quotes and then close your browser.
15. In NetBeans, stop both Customer Quotes and Sales Insight.applications.

In the last task, you executed a Federated SSO authentication between Oracle Identity Cloud Service and the Customer Quotes application.
After the authentication, you requested Urgent Quotes. This triggered an authorization request from Customer Quotes to Oracle Identity Cloud Service to access the Sales Insight's quote API, which you authorized on the consent page.
After your consent, Customer Quotes requested the Sales Insight's quote API passing the access token. Sales Insight validated the access token signature, and then returned a list of quotes that appeared on the Customer Quotes page.

The Federated SSO followed the same steps that you explored in the Oracle Identity Cloud Service: Integrating a Custom Client Application tutorial.

The authorization request with consent and the Sales Insight access token validation flow is displayed in the following steps:

View Image

Processing Steps:

0. The Sales Insight resource server application is launched. During startup, the resource server obtains the Oracle Identity Cloud Service signing key.
   The resource server uses the signing key in future requests to validate access token signatures.
1. The resource owner (the end user) accesses the Customer Quotes application (https://localhost:8181/cquotes), and then clicks Urgent Quotes.
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=http://localhost:8080/salesinsight/quote

Parameters informed with the authorization code request URL

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's the authorization code.
redirect_uri	https://localhost:8181/cquotes/return	The URL where the authorization code should be sent after the resource owner authenticates/authorizes in Oracle Identity Cloud Service
scope	http://localhost:8080/salesinsight/quote	The scope controls what data the Customer Quotes application wants to access/process on behalf of the resource owner. Because the user is requesting quotes, we request the http://localhost:8080/salesinsight/quote 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 access the Sales Insight's quotes (scope http://localhost:8080/salesinsight/quote) on behalf of the resource owner .
5. Oracle Identity Cloud Service checks whether the resource owner already authorized the access. If not, it presents the consent page that describes what access the Customer Quotes application is requesting.
6. The resource owner submits the consent (for example, Allow) to Oracle Identity Cloud Service.
7. If the consent is Allow, Oracle Identity Cloud Service prepares a response to the Customer Quotes application using the following format:
   

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

URL and attributes returned from Identity Cloud Service to Customer Quotes

Attribute	Sample Value	Description
url	https://localhost:8181/cquotes/return	The URL where Customer Quotes wants the authorization code sent
code	DUllQVElPTl9LRVkxNCB7djF9NCA=	The authorization code created by 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, attributes, and headers.
    

URL and Attributes:

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 after the resource owner granted consent

Headers and Parameters:

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

access token header attributes

Header	Sample Value	Description
Authorization	Basic Y29udHJhdHVsYXRpb25zeW91Zm91bmRhbmVhc3RlcmVnZzppbnNpZGV0aGlzdHV0b3JpYWwK	The Customer Quotes application client_id and client_secret 64-bit encoded: client_id:client_secret
Accept	*/*	The type of response the Customer Quotes application expects

11. Oracle Identity Cloud Service validates the request and returns an access token to the Customer Quotes application. The access token contains information about what scopes the Customer Quotes application can request on behalf of the resource owner. The Customer Quotes application can use this token when requesting APIs on behalf of the resource owner.

The Oracle Identity Cloud Service access tokens are in JSON Web Token (JWT) format. To know more about JWTs, visit the JSON Web Token page.

12. The Customer Quotes application requests the Sales Insight quote API (http://localhost:8080/salesinsight/quote) passing the access token as an argument:

http://localhost:8080/salesinsight/quote?token=access_token

13. Sales Insight validates:
• The access token signature against the Oracle Identity Cloud Service signing key (obtained by the application during step 0).
  A valid signature means that the access_token is legit
• The access token audience and scope in order, to confirm that the access token is valid for the Sales Insight quote API: (http://localhost:8080/salesinsight/quote)
• The access token expiration time in order, to confirm that the token is still valid.
14. If the access token is successfully validated, the Sales Insight resource server application processes the request and returns quotes to the Customer Quotes application.
15. The Customer Quotes application displays quotes to the resource owner.

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 Client 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 APIs

• Oracle Identity Cloud Service: Managing Groups Using REST APIs

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