Before You Begin
In this tutorial, you learn to integrate Oracle Identity Cloud Service with a custom resource server application using OAuth 2.0.
Time to Complete
Oracle Identity Cloud Service supports the following frameworks for Federated Single Sign-On (SSO) and authorization integration with custom applications:
- 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.
- 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:
- 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.
- 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.
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 (
- Sales insight (
- Sales reports (
- Sales pipeline (
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.
Launching Sales Insight
In this task, you launch the Sales Insight sample code in Glassfish, a J2EE Application Server bundled with the NetBeans IDE.
- Launch NetBeans, and then click File > Open Project.
- 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.
- The salesinsight entry appears under Projects.
- Right-click salesinsight, and then click Run.
- 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.
NetBeans deploys the Sales Insight (salesinsight) application on Glassfish.
- To confirm that Sales Insight is working, access:
The application returns a random list of quotes in html format. Tip: You can see the return information without providing an access token because Sales Insight is not yet protected.
- Optionally, access other REST APIs, such as:
At this point, you are running the Sales Insight application on your own machine at this location:
In the next steps, you register this application in Oracle Identity Cloud Service.
Configuring a Resource Server Application in 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.
- In the Oracle Identity Cloud Service console, expand the Navigation Drawer , click Applications, and then click Add.
- Select Confidential Application.
Sales Insightas the Application Name,
Server that provides via REST APIs sales insight for our teamas Description, and click Next.
- Click Configure this application as a client now, select Client Credentials as Allowed Grant Types, and then click Next.
- 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.
Enter the scopes according to the table.
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
Compare the Allowed Scopes table to the image below, and then click Finish.
Save the Client ID and the Client Secret, and then click Close.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.
- 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.
Integrating Sales Insight and 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.
- Return to NetBeans, expand Web Pages > WEB-INF, and then open the
- 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.xmlfile: Tip: The snippet above enables an authorization filter for any request to the Sales Insight resource server application. The filter is provided by the
- 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.
Update the values for
CLIENT_SECRET, and the
- Save the ResourceServerConfig.java file.
|| The values that you obtained while creating the Sales Insight application in Oracle Identity Cloud Service.
|IDCS_URL||The Oracle Identity Cloud Service url. For example:
//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";
Configuring the Integration Between Sales Insight and Oracle Identity Cloud Service
- In NetBeans, right-click salesinsight, and then click Run.
- Select Output > GlassFish Server 4.1.1, and then confirm that the following message appears: Signing Key from IDCS successfully loaded!
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.
- 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.
Sales Insight returns the message: Error While Validating Token: No access token provided.
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.
Consuming the Sales Insight APIs
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
- In the Identity Cloud Service console, expand the Navigation Drawer , click Applications, and then click Customer Quotes.
- Click Configuration, and then expand Client Configuration.
- In the Accessing APIs from Other Applications section, click Add (next to Allowed Scopes).
- The Sales Insight application is listed as an available resource for selection. Click the arrow next to Sales Insight.
- 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.
- The Allowed Scopes table now displays the scopes that Customer Quotes can access from the Sales Insight resource server. Click Save.
Configuring the Customer Quotes Code to Request the Sales Insight APIs
- Open the cquotes sample code in NetBeans. 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.
- In the ClientConfig.java file, update the
IS_RESOURCE_SERVER_ACTIVEproperty value to true.
- Save the ClientConfig.java file.
Tip: The Customer Quotes application is pre-configured with a code to request the Sales Insight APIs when the resource server is active.
//SCOPES LEVERAGED BY YOUR APPLICATION public static final boolean IS_RESOURCE_SERVER_ACTIVE = true;
Testing the Integration
- In your browser, sign out of Oracle Identity Cloud Service.
- In NetBeans, right-click salesinsight, and then click Run.
- 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
- Return to NetBeans, right-click cquotes, and then click Clean.
- Right-click cquotes, and then click Run.
- In your browser, launch Customer Quotes in HTTPS:
- Click Login with Identity Cloud Service.
- Authenticate using your credentials.
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.
- Click Urgent Quotes. A consent screen from Oracle Identity Cloud Service appears. 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.
- Click Don't Allow. The Customer Quotes application displays a
- Click Go back home.
- 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.
- Optionally, explore the other options within in the Customer Quotes page.
- Sign out of Customer Quotes and then close your browser.
- In NetBeans, stop both Customer Quotes and Sales Insight.applications.
Understanding the Integration
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:Processing Steps:
- 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.
- The resource owner (the end user) accesses the Customer Quotes application (
https://localhost:8181/cquotes), and then clicks Urgent Quotes.
- The Customer Quotes application prepares an authorization code request URL using the following format:
- The Customer Quotes application redirects the resource owner to the authorization code URL.
- 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 .
- 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.
- The resource owner submits the consent (for example, Allow) to Oracle Identity Cloud Service.
- If the consent is Allow, Oracle Identity Cloud Service prepares a response to the Customer Quotes application using the following format:
- Oracle Identity Cloud Service redirects the resource owner back to the Customer Quotes application.
- The Customer Quotes application extracts the authorization code from the resource owner request.
- The Customer Quotes application requests an access token from Oracle Identity Cloud Service using the following URL, attributes, and headers.
- 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 Customer Quotes application requests the Sales Insight quote API (
http://localhost:8080/salesinsight/quote) passing the access token as an argument:
- Sales Insight validates:
||The Customer Quotes unique Application ID (
||The expected response from Oracle Identity Cloud Service. In this step, it's the authorization code.|
||The URL where the authorization code should be sent after the resource owner authenticates/authorizes in Oracle Identity Cloud Service|
|| 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
||The URL where Customer Quotes wants the authorization code sent|
||The authorization code created by Identity Cloud Service|
URL and Attributes:
||Since you're using an
||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=*/*
||The Customer Quotes application client_id and client_secret 64-bit encoded:
||The type of response the Customer Quotes application expects|
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.
- 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: (
- The access token expiration time in order, to confirm that the token is still valid.
Want to Learn More?
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:
To learn more about the REST APIs, explore the following tutorials and documents:
- Developer(s): Frederico Hakamine.
- Contributor(s): Vinicius Hakamine and Paulo Albuquerque.