Use OAuth 2.0 in a Custom Resource Server Application


Options



Before You Begin

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:
OAuth 2.0 authorization flow. Description for each step in the optional section Understanding the Integration
Description of this 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.

Launching Sales Insight

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.
    salesinsight project opened in NetBeans
    Description of this 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.
    Glassfish credentials window
    Description of this image
  6. NetBeans deploys the Sales Insight (salesinsight) application on Glassfish.
  7. To confirm that Sales Insight is working, access: http://localhost:8080/salesinsight/quote
    The application returns a random list of quotes in html format.
    Sales Insight - Quote service output.
    Description of this image
    Tip: You can see the return information without providing an access token because Sales Insight is not yet protected.
  8. 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.

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.

  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.
    Add application in Identity Cloud Service UI - Configuring application resources.
    Description of this image
  6. Enter the scopes according to the table.

    Add Scope dialog window in Identity Cloud Service UI - enter scope, description, and select requires consent.
    Description of this 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.

    Sales Insight Scopes registered in Identity Cloud Service.
    Description of this image
  8. Save the Client ID and the Client Secret, and then click Close.

    Application Added screen in Identity Cloud Service UI - Client ID and Secret.
    Description of this 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.

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.

  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:
    web.xml file. Servlet filter snippet uncommented.
    Description of this 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.

  5. 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.
    Application Added screen with Client ID and Secret.
    Description of this 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";
    
  6. Save the ResourceServerConfig.java file.

Configuring the Integration Between Sales Insight and Oracle Identity Cloud Service

  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!
    Customer Quotes - Login with Identity Cloud Service
    Description of this 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
  4. Sales Insight returns the message: Error While Validating Token: No access token provided.

  5. Access: http://localhost:8080/salesinsight/quote?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
  6. 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

  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).
    Customer Quotes - Adding new scopes to the application
    Description of this image
  4. The Sales Insight application is listed as an available resource for selection. Click the arrow next to Sales Insight.
    Customer Quotes - Adding scopes from Sales Insight
    Description of this 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.
    Customer Quotes - Selecting all scopes from Sales Insight
    Description of this image
  6. The Allowed Scopes table now displays the scopes that Customer Quotes can access from the Sales Insight resource server. Click Save.
    Customer Quotes - Updating the application configuration with new scopes
    Description of this image

Configuring the Customer Quotes Code to Request the Sales Insight APIs

  1. Open the cquotes sample code in NetBeans.
    NetBeans - cquotes project opened
    Description of this 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.
  3. //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.
  4. Save the ClientConfig.java file.

Testing the Integration

  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
    Sales Insight call without a token
    Description of this 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/
    Customer Quotes home
    Description of this image
  7. Click Login with Identity Cloud Service.
  8. Authenticate using your credentials.
    Authentication in Identity Cloud Service
    Description of this 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.
    Customer Quotes application - Welcome screen with additional API calls from Sales Insight
    Description of this image
  9. Click Urgent Quotes. A consent screen from Oracle Identity Cloud Service appears.
    Identity Cloud Service - Consent Page
    Description of this 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.
    Customer Quotes - user_denied error
    Description of this 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.
    Customer Quotes - displaying quotes from Sales Insight
    Description of this 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.

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:

OAuth 2.0 authorization flow. Description for each step below</a>
Description of this image
Processing Steps:
  1. 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.
  2. The resource owner (the end user) accesses the Customer Quotes application (https://localhost:8181/cquotes), and then clicks Urgent Quotes.
  3. 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
  4. 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
  5. The Customer Quotes application redirects the resource owner to the authorization code URL.
  6. 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 .
  7. 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.
  8. The resource owner submits the consent (for example, Allow) to Oracle Identity Cloud Service.
  9. 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
  10. 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
  11. Oracle Identity Cloud Service redirects the resource owner back to the Customer Quotes application.
  12. The Customer Quotes application extracts the authorization code from the resource owner request.
  13. The Customer Quotes application requests an access token from Oracle Identity Cloud Service using the following URL, attributes, and headers.
  14. 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
  15. 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.
  16. 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.

  17. The Customer Quotes application requests the Sales Insight quote API (http://localhost:8080/salesinsight/quote) passing the access token as an argument:
  18. http://localhost:8080/salesinsight/quote?token=access_token
  19. 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.
  20. If the access token is successfully validated, the Sales Insight resource server application processes the request and returns quotes to the Customer Quotes application.
  21. The Customer Quotes application displays quotes to the resource owner.

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:

Credits

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