Subsurface data management: How to authenticate OSDU on AWS sandbox

Introduction

Data is fueling subsurface innovation, yet getting the data into a format that enables novel analytical approaches and enables end users to focus on using novel data insights to solve problems is a key challenge.  The Open Group OSDU™ Forum is developing a standard data platform for the oil and gas industry, which will reduce data silos and put data at the center of the subsurface community.

OSDU on AWS is a secure, reliable, cost-effective, and performant implementation of the OSDU standard. With OSDU on AWS, companies can focus on the truly differentiating parts of their business, and leave the undifferentiated heavy lifting of subsurface data management to AWS.

This blog explains how to authenticate to your OSDU on AWS sandbox. We will create a simple Node.js application which authenticates to your OSDU on AWS sandbox.

Overview of solution

This blog is designed to support customers who have recently installed an OSDU on AWS environment and must authenticate their environment in order to search and consume data.  This is the first blog post in a series that will provide support for getting started with your OSDU on AWS environment.

In this post, we explain how to authenticate to your OSDU on AWS sandbox. To do this, we will create a simple Node.js application and authenticate to your OSDU on AWS sandbox. This will enable OSDU on AWS for a range of functionality including searching and data ingestion.

Prerequisites:

To build and deploy the solution, you will need:

1. An OSDU on AWS deployment with Release 2 installed and configured in an AWS account, and credentials (user name and password) to access the platform.
2. TNO and Volve data loaded into your OSDU on AWS account.
3. Download and install Node.js.
4. Download and install Visual Studio Code IDE.

Solution

To build out the solution, we will be working both on the AWS Management Console and on your local machine. We will first create the Node.js application, then authenticate to your OSDU on AWS sandbox.

Section 1: Create the Node.js application

1. Open a command prompt or terminal and create a directory for your Node.js application. Then switch to the directory as shown.
   
2. Run the npm init –y command to setup an npm (Node package manager) package with default values.You should see a package.json file created in the directory with the values shown in the previous screenshot.
3. Open Visual Studio Code IDE. Open the folder where you created the Node.js package as shown.
   
4. You will now see your folder under Explorer with the package.json file as shown.
   
5. Create a new file in your folder that contains the package.json file and name it index.js. View the following screenshots for reference.
   You will see the new file saved as index.js as shown.
   
6. Copy the following code to the index.js file.

   global.fetch = require('node-fetch');
   var AmazonCognitoIdentity = require('amazon-cognito-identity-js');
   var jwtDecode = require('jwt-decode');
   var axios = require("axios");
   var https = require('https');
   
   var authenticationData = {
       Username: '<User Name>',
       Password: '<Password>',
   };
   
   var authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails(authenticationData);
   var poolData = {
       UserPoolId: '<Cognito User PoolId>',
       ClientId: '<Cognito Client Id>',
   };
   
   var userPool = new AmazonCognitoIdentity.CognitoUserPool(poolData);
   var userData = {
       Username: authenticationData.Username,
       Pool: userPool
   };
   
   var cognitoUser = new AmazonCognitoIdentity.CognitoUser(userData);
   
   cognitoUser.authenticateUser(authenticationDetails, {
       onSuccess: function (result) {
           var accessToken = result.getAccessToken().getJwtToken();
           console.log("Access Token: ");
           console.log(accessToken);
           
       },
   
       onFailure: function (err) {
           console.log(err);
       },
   });
   

Section 2: Authenticate to your OSDU on AWS account

7. In the code from step 6, replace the <User Name> and <Password> place holders with your Amazon Cognito user name and password provided to you. If you do not have a <User Name> and <Password> reach out to your OSDU on AWS contact.

8. Replace the <Cognito User PoolId> and <Cognito Client Id> placeholders with your Amazon Cognito User Pool ID and Amazon Cognito ClientID.You can find your Amazon Cognito User Pool ID by going to Amazon Cognito page and -> click on Manage User Pools as shown.
   Click on the osduonaws-UserPool as shown:
   
9. You will be taken to the General settings on the User Pool page. Copy the Pool ID as shown below and replace the <Cognito User PoolId> placeholder in your code with it.
   
10. Click on App client settings under App integration.
    
11. Scroll down until you find App client osduonaws-DefaultAppClient. Copy the Client ID and replace the <Cognito Client Id> placeholder in your code with it. It is very important you copy the DefaultAppClient Client ID and not the ClientSecret ID, otherwise you will not be able to connect.
    
12. Make sure you have also replaced the <User Name> and <Password> placeholders with your correct Amazon Cognito user name and password provided to you.
13. Replace the contents of the package.json file with the code below that contains dependencies required by the application.

    {
      "name": "osduauth",
      "version": "1.0.0",
      "description": "",
      "main": "index.js",
      "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
      },
      "keywords": [],
      "author": "",
      "license": "ISC",
      "dependencies": {
        "amazon-cognito-identity-js": "^3.0.15",
        "aws-sdk": "^2.504.0",
        "axios": "^0.20.0",
        "jwt-decode": "^2.2.0",
        "node-fetch": "^2.6.1"
      }
    }
    

14. Open a new Terminal in Visual Studio Code as shown.You will see the new Terminal Window below the code.
15. Run the npm install command to download the dependencies as shown.
16. You will see the dependency packages installed.
17. Run the command node index.js as shown.
18. Once you are authenticated you will see the Access Token as shown.

Code Walkthrough

As you have successfully authenticated to the OSDU on AWS sandbox, we will now go over the code. Starting from the beginning, the following code imports the dependencies.

global.fetch = require('node-fetch');
var AmazonCognitoIdentity = require('amazon-cognito-identity-js');
var jwtDecode = require('jwt-decode');
var axios = require("axios");
var https = require('https');

The code below is used to configure the Amazon Cognito user information which includes user name, password, Amazon Cognito User Pool ID, and Amazon Cognito Client ID. We pass this information to the CognitoUser method in the AmazonCognitoIdentity object. 

var authenticationData = {
      Username: '<User Name>',
      Password: '<Password>',
      };

 var authenticationDetails = new AmazonCognitoIdentity.AuthenticationDetails(authenticationData);
var poolData = {
    UserPoolId: '<Cognito User PoolId>',
    ClientId: '<Cognito Client Id>',
};

var userPool = new AmazonCognitoIdentity.CognitoUserPool(poolData);
var userData = {
    Username: authenticationData.Username,
    Pool: userPool
};

var cognitoUser = new AmazonCognitoIdentity.CognitoUser(userData);

The code below authenticates the user and returns an access token.

cognitoUser.authenticateUser(authenticationDetails, {
    onSuccess: function (result) {
        var accessToken = result.getAccessToken().getJwtToken();
        console.log("Access Token: ");
        console.log(accessToken)
    },

    onFailure: function (err) {
        console.log(err);
    },
});

Conclusion

In this blog, we have demonstrated authenticating to OSDU on AWS sandbox using JavaScript and Node.js. Once this is complete, you will be able to search for data from your OSDU on AWS sandbox, which will be demonstrated in a future blog post.