Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Node.js Web Applications

Before You Begin

This 15 minutes tutorial shows you how to use Oracle Identity Cloud Service's Software Development Kit (SDK) for the Node.js framework to enable a sample web application to authenticate with Oracle Identity Cloud Service.

Series

This is a tutorial in the Use Oracle Identity Cloud Service's Software Development Kit (SDK) series. Read them in any order.

Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Java Web Applications
Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Node.js Web Applications
Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in Python Web Applications
Use Oracle Identity Cloud Service's Software Development Kit (SDK) for Authentication in .NET Web Applications

Background

Oracle Identity Cloud Service provides a Software Development Kit (SDK) that you download from the console, and can use to integrate Node.js web applications with Oracle Identity Cloud Service.

The Node.js SDK is available as a passport strategy, called passport-idcs, and must be added to the Node.js web application source code's /node_modules folder.

To help you understand how to use the SDK, this tutorial uses a sample web application as a reference.

Important: The sample web application isn't meant to be published to production and isn't concerned about the language’s specific best practices, such as data handling, patterns, security, and so on. The sole purpose of the sample web application is to address the recommended approach to integrate Oracle Identity Cloud Service and a custom application using the SDK.

What Do You Need?

A basic knowledge of Node.js framework and JavaScript programming language to understand the code logic presented in this tutorial.
To install the Current Node.js binaries in your desktop.
To download the Node.js sample web application as a zip file, and extract its content to the c:\temp folder of your desktop.
Access to an instance of Oracle Identity Cloud Service, and rights to download the SDK from the console and to add a confidential application.

Download the SDK in the Sample Web Application

In the Identity Cloud Service console, expand the Navigation Drawer , click Settings, and then click Downloads. The list of files to download appears.
Click Download to download the Identity Cloud Service SDK for Node.js SDK file, and save the zip file.

Note: You install the SDK after installing the other third-party libraries.

Register the Sample Web Application with Oracle Identity Cloud Service

The sample web application needs a Client ID and Secret to establish communication with Oracle Identity Cloud Service. You also need to configure API permissions that must be granted to the sample web application. This section explains how to register the sample web application with Oracle Identity Cloud Service.

In the Identity Cloud Service console, expand the Navigation Drawer , click Applications.
In the Applications page, click Add.

Description of this image
In the Add Application chooser dialog, click Confidential Application.
Populate the Details pane as follows, and then click Next.
- Name: SDK Web Application
- Description: SDK Web Application
In the Client pane, select Configure this application as a client now, and then populate the fields of this pane, as follows:
- Allowed Grant Types: Select Client Credentials and Authorization Code.
- Allow non-HTTPS URLs: Select this check box. The sample application works in non-HTTPS mode.
- Redirect URL: http://localhost:3000/callback
- Post Logout Redirect URL: http://localhost:3000
In the Client pane, scroll down, click the Add button below Grant the client access to Identity Cloud Service Admin APIs.

Description of this image
In the Add App Role dialog window, select Authenticator Client and Me in the list, and then click Add.
Click Next in the Client pane and in the following panes until you reach the last pane. Then click Finish.
In the Application Added dialog box, make a note of the Client ID and Client Secret values (because your web application needs these values to integrate with Oracle Identity Cloud Service), and then click Close.

Description of this image
To activate the application, click Activate.

Description of this image
In the Activate Application? dialog box, click Activate Application.
The success message The SDK Web Application application has been activated. appears.
In the Identity Cloud Service console, click the user name at the top-right of the screen, and click Sign Out.

Update the Sample Web Application

In this section, you update the sample application code to make it use Oracle Identity Cloud Service's SDK for Node.js programming language.

Populate the values of the Client ID , Client Secret , and Oracle Identity Cloud Service's Tenant and domain
Note: It is important to update the fields above accordingly before continuing to the next sections.

Edit the c:\temp\nodejs\auth.js file, update the lines in bold, and then save the file.

//Oracle Identity Cloud Service connection parameters as a json var
var ids = {
  oracle: {
    "ClientId": "",
    "ClientSecret": "",
    "ClientTenant": "",
    "IDCSHost": "https://%tenant%.",
    "AudienceServiceUrl" : "https://.",
    "TokenIssuer": "https://identity.oraclecloud.com/",
    "scope": "urn:opc:idm:t.user.me openid",
    "logoutSufix": "/oauth2/v1/userlogout",
    "redirectURL": "http://localhost:3000/callback",
    "LogLevel":"warn",
    "ConsoleLog":"True"    
  }
};
module.exports = ids;

Run the Sample Web Application

In this section of the tutorial, you prepare, run, and test the sample web application.

Open a command prompt, navigate to the c:\temp\nodejs folder, and enter npm install to install all of the necessary modules, which are specified in the package.json file.
At the end of the command the following message appears: npm WARN nodejs-sdk-oracle-idcs@1.0.0 No repository field.

Note: If you're behind a proxy, then set up npm's proxy before running the npm install command.

Note: If the previous command fails to install the packages, run the following command before npm install --global windows-build-tools, and then run npm install
Open the SDK zip file and extract the passport-idcs folder into the sample web application source code's node_modules folder. The source code structure of the sample web application must be similar to the one below.
```
c:\temp\nodejs\
     		models\
     		node_modules\
        		     ...
          		     passport-idcs\
	                     ...
     		public\
     		routes\
     		views\
     		app.js
     		...
```
Note: Make sure to run the npm install command before extracting the Node.js SDK package into the sample web application source code's node_modules folder.
In the command prompt, run the npm start command to start the application.
The Server started on port 3000 message appears in the command prompt window.
Open a browser window, access the http://localhost:3000 URL, and click Log in.
In the Login page, click the Oracle red icon.

Description of this image
In the Oracle Identity Cloud Service Sign In page, sign in using your Oracle Identity Cloud Service credentials.
After you sign in to Oracle Identity Cloud Service successfully, the browser is redirected to the /home page. The name of the logged-in user appears at the top-right side of the page.
In the left menu, click My Profile.
Verify that information associated with your profile appears in the center of the page.

Description of this image
Click Log Out on the upper-right corner. The sample application finalizes the user session and redirects the browser to Oracle Identity Cloud Service's logout URL.

After Oracle Identity Cloud Service logs the user off, it redirects the user browser to the sample application index page. This behavior happens because the sample application adds two parameters post_logout_redirect_uri and id_token_hint to the Oracle Identity Cloud Service logout URL, as per below:

https://./oauth2/v1/userlogout?post_logout_redirect_uri=http%3A//localhost%3A3000&id_token_hint=<ID_TOKEN>

The post_logout_redirect_uri parameter value must match the Post Logout Redirect URL parameter value you set during Register the Sample Web Application with Oracle Identity Cloud Service