Before You Begin
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
Oracle Identity Cloud Service supports the following frameworks for federated SSO and authorization integration with custom applications:
- OAuth 2.0: Framework for authorization, commonly used for third-party authorization requests with consent. See OAuth for more information.
- 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:
- 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.
- 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.
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.
Import the Oracle Identity Cloud Service Certificate in Glassfish
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
- Launch your browser. (in this tutorial, we are using Google Chrome on Windows)
- Access the Oracle Identity Cloud Service UI.
- In the browser address bar, click view website information (locker icon), and then click Details.
- Click View Certificate.
- Click Details then click Copy to File
- Click Next, select Base-64 encoded X.509 (.CER), and then click Next.
- Save the certificate as
oracle.cerin a temporary folder such as
D:\temp, click Next and then Finish.
- Click OK, close the certication pop-up and your browser.
Import Oracle Identity Cloud Service Certificate in Glassfish
- Launch Netbeans.
- Click Services, expand Servers, right-click Glassfish Server, and then click Properties.
- Record the Glassfish domains folder. Tip: You will import the Identity Cloud Service certificate under this folder.
- Close Netbeans.
- Launch a command prompt as administrator. Tip: in Windows 7, click the start menu, type
where keytoolto confirm that the keytool utility is available from your OS classpath. The prompt should return a message containing the keytool location:
- Navigate to Netbeans' Glassfish domain folder and run the keytool command (You recorded the domain folder earlier in this tutorial):
- In the confirmation prompt, enter
- To confirm the import was a success, enter the command:
- Close the command prompt.
cmd, right-click the
cmd.exeshortcut, click Run as Administrator, and then click Yes.
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):
where keytool C:\Program Files\Java\jdk1.8.0_60\bin\keytool.exe
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
cd %GLASSFISH_DOMAIN_FOLDER%\domain1\config keytool -import -keystore "cacerts.jks" -trustcacerts -file "D:\temp\oracle.cer" -alias idcs -storepass changeit
The terminal should display the certificate fingerprint like in the following example:
keytool -list -keystore "cacerts.jks" -alias idcs -storepass changeit
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
Launching Customer Quotes
In this task, you launch the Customer Quotes application (sample code) in Glassfish, a J2EE Application Server bundled with the Netbeans IDE.
- 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
- Access Netbeans and click File > Open Project.
- Navigate to the folder where you cloned the idm-samples repository. Select the cquotes folder, and then click Open Project.
- 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.
- Right-click cquotes, and then click Run. Tip: If prompted for Select Deployment Server, select GlassFish and continue.
- 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 (
- Access the following URL:
- 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:
In the next steps, you integrate this application with Oracle Identity Cloud Service.
Configuring a Client Application in 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.
- In the Identity Cloud Service console, expand the Navigation Drawer , click Applications, and then click Add.
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.
Customer Quotesas the Name,
Web application that works as a hub for all of your quotations. Access quotes and insights from customers from your browseras the Description, and then click Next.
Select Configure this application as a client now.
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
URL where users will be redirected to cquotes after authentication/authorization in Oracle Identity Cloud Service Logout URL
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
URL where the resource owner should be redirected after the Oracle Identity Cloud Service logout.
- Click Next in the following panes until you reach the last pane. 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 a credential (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 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.
Integrating Customer Quotes and Oracle Identity Cloud Service
In this task, you configure the Customer Quotes application to connect with Oracle Identity Cloud Service during authentication.
- 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.
- Save the ClientConfig.java file.
|| 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:
//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";
Testing the Integration
- Return to your browser and make sure that you are not logged in to Oracle Identity Cloud Service.
- In Netbeans, right-click cquotes, and then click Run. Your web browser displays the Customer Quotes application.
https://localhost:8181/cquotes/(to launch the Customer Quotes application in HTTPS).
- Click Login with Identity Cloud Service.
- Authenticate with your credentials.
- After a successful authentication, Oracle Identity Cloud Service redirects you back to the Customer Quotes application, which displays a welcome message.
- 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.
- 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.
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.
Optional Understanding the Integration
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:
- The resource owner 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 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 get more information about the resource owner (scope
- Oracle Identity Cloud Service checks whether the resource owner is authenticated. If not, it presents the login page.
- The resource owner submits the credentials to Oracle Identity Cloud Service.
- 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:
- 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 and headers:
Access Token request attributes Attribute Sample Value Description grant_type
Since you're using an
authorization_codeto request an Access Token from Oracle Identity Cloud Service, the grant type must be "
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
The Customer application client_id and client_secret 64-bit encoded in the format:
The type of response the Customer Quotes application expects.
- Oracle Identity Cloud Service validates the request and returns the following tokens to the Customer Quotes application:
- The Customer Quotes application processes the
id_tokenJWT token, and then extracts the resource owner information returned by Oracle Identity Cloud Service, such as name and email.
- The Customer Quotes application displays the home page containing information about the resource owner, such as name and email.
||The Customer Quotes unique Application ID (
||The expected response from Oracle Identity Cloud Service. In this step, it is the authorization code.|
||The URL where the authorization code should be sent after the resource owner completes authentication/authorization with Oracle Identity Cloud Service.|
||Scope contols what data the Customer Quotes application can access/process on behalf of the resource owner. Because we are using OpenID Connect, we request
||The URL where the authorization code should be sent to the Customer Quotes application|
||The authorization code created by Oracle Identity Cloud Service|
|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
The Oracle Identity Cloud Service tokens are in JSON Web Token (JWT) format. See JWT for more information on JSON Web Tokens.
Optional Display application for users in Identity Cloud Service
In this task, you can make Oracle Identity Cloud Service to display the Customer Quotes application under My Apps page for specific users.
- In the Identity Cloud Service console, expand the Navigation Drawer , click Applications, and then click Customer Quotes.
- Update the fields as follows and click Save.
- Under Users, click the particular user that you want to assign access to the application, click Access.
- 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:
|Application Icon||Upload the image provided with cquotes sample code under
|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.
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): Andressa Silva, Paulo Albuquerque, and Vinicius Hakamine.