Digital Developer Conference: Hybrid Cloud. On Sep 22 & 24, start your journey to OpenShift certification. Free registration

Quickly stand up a protected web interface for a cloud-native app on IBM Cloud

This tutorial is a quick-start guide for developing a Node.js starter application on IBM Cloud. These days even small applications or hackathon projects benefit from authentication and protected areas. To serve this need, the cloud-native sample app in this tutorial is a protected web interface application, which uses the passport module for OpenID Connect (OIDC) authentication to protect specific pages.

Prerequisites

Steps

  1. Create the Node.js starter application
  2. Setup the CD/CD pipeline with github
  3. Use an existing sample application
  4. Enable protection in the sample app with OIDC
  5. Add more pages to the website

Step 1: Create the Node.js starter application in IBM Cloud

IBM Cloud provides starter kits for different technologies and runtimes. Using these apps eliminates the need to manually install the required framework and gets every developer up and running in minutes.

  1. Log in to your IBM Cloud account.

  2. Create a Cloud Foundry sample app using the SDK for Node.js application runtime. Chose a region and a name for your app before you click Create.

    Screen shot of Create a Cloud Foundry sample app in IBM Cloud

The service will start automatically.

Screenshot of service starting

Step 2: Set up a continuous delivery pipeline with github

Collaboration is essential in software projects. We use the de facto standard github to store our code. This method also enables us to adapt another important pattern for software development, removing the local build that always depends on your local installation and move the whole build and deploy processing into the cloud as well. This guarantees reproduceable quality and decouples code packaging for every developer with access to the code in github.

  1. In the dashboard for your service, select Overview.

    Screen shot of sample app in IBM Cloud

  2. In the Continuous delivery box, click the Enable continuous delivery link.

  3. On the Continuous Delivery Toolchain page, in the Tool Integrations section, select New from the Repository type drop-down. This will create a new GitHub repository to store your code in.

    Screen shot of continuous delivery toolchain in IBM Cloud

  4. To work correctly, the pipeline requires an API key. Click the Delivery Pipeline tab, and either specify the API key for your repository or use the wizard shown in the following screenshot to generate a new one.

    Screen shot of creating a new API key in IBM Cloud

The Continuous Delivery toolchain is now set up and ready to use.

Screen shot of toolchain in IBM Cloud

Step 3: Use an existing sample application as a starter kit

Starting from zero is mostly not required in IBM Cloud because there are already great starter kits that are available to use. This tutorial leverages one sample app as the base layer and then we enhance it with the functionality we need. To do so we need to load the sample application and copy it to our own github repository.

  1. In the toolchain dashboard, click the Git card to view the details of your GitHub repository. Because the git repository is a new repository, the screen will look like the following screenshot and include the command line instructions.

    Screen shot of git repo in toolchain in IBM Cloud

  2. The message at the top of the page explains that a personal access token is needed. So, click this link to create one. This will bring you to the User Settings.

  3. Name the personal access token, and give the access token full control, since you need to push code changes to the repository.

    Screen shot of defining personal access token for git repo in IBM Cloud

  4. Copy the token string. If you forget to copy it, just revoke the token and create it again.

  5. To test the setup and api-key, start with the clone of this new repository. To find your repository URL, click the Clone button, and then click the copy button in the Clone with HTTPS field.

    Screen shot of repoistory URL for git repo in IBM Cloud

    Then, use the following git clone command:

    git clone https://<your repository>/<yourFilename>.git

    When prompted, use your cloud email address and the generated personal access token for authentication.

    Screen shot of git clone command output

  6. Back on the IBM cloud console, click the Visit App URL link (which you will use later used as yourNodeAppUrl).

    Screen shot of Visit App URL link in IBM Cloud console

    Because there is no app code pushed to the GitHub repository, the “Hello World!” fallback screen displays.

    Screen shot of Hello World fallback screen of sample Node.js app

    The Getting Started tab explains how to access the sample code and use it locally.

  7. Because we set up our toolchain for deployment, now let’s clone the get-started-node sample which is available here: https://github.com/IBM-Cloud/get-started-node.

    git clone https://github.com/IBM-Cloud/get-started-node

  8. Copy the get-started-node sample code to your own file structure on the local development system from cloning your new GitHub repository earlier.

  9. Use the following git commands to commit the files to your new GitHub repo for our sample app. First, add the files:

    git add .

    Next, commit the changes:

    git commit -m "initial sample push"

    Screen shot of output for git commit command

    Finally, push the changes to the server:

    git push

    Screen shot of output for git push command

    Tip: If you do not want to enter the personal access token each time, update the config in the .git file.

    Screen shot of editing the git file to contain your personal access token

    After entering the git commands, you will see the deployment pipeline kick-off and put your changes up in your web app.

    Screen shot of deployment pipeline building and deploying changes

Give it some time to complete, and then open the app URL as before. Now, the new Welcome page is displayed.

Screen shot of new welcome page in the sample app

The small, simple web app is now running. However, the content is unprotected. Let’s protect it using OpenID Connect.

Step 4: Enable protection in the sample application

For most websites, you typically want some protected areas or at least you want to use a user profile for some additional functions. Node.js provides a few different modules to protect websites. I will use the module Passport for this tutorial. The Passport module supports different authentication mechanism and providers. For this tutorial we will use Google as the OIDC provider.

You can access the json and javascript files in my GitHub repo for this tutorial.

You can clone my repository by using this command: git clone https://eu-de.git.cloud.ibm.com/sascha.schefenacker/saschaStarter.git

  1. Set up a Google OIDC project and configure the clientID + clientSecret on the Google Developer’s Console. Read more about Google OIDC projects in their developer docs.

    a. Open the Google API Console to create a new project: https://console.developers.google.com/apis/dashboard

    b. Open the hamburger menu on the top left, and select APIs & Services > OAuth consent screen.

    c. Select the External user type, and click Create.

    d. Enter the application name and authorized domain, and click Create.

    e. Switch to the Credentials tab, and click CREATE CREDENTIALS in the top area to select an OAuth client ID.

    f. Enter a web client name and the redirect URI we will configure in the next steps as well on client side. Note: You need to use the retrieved yourNodeAppUrl from a previous step to construct the callback URL (https://<yourNodeAppUrl>/auth/google/callback).

    g. After you click CREATE, a screen appears for you to copy and save the ClientID and clientSecret.

    You have now configured a new Google authentication and stored the required credential.

  2. Switch back to your cloned git repository. Copy the package.json file from my sample repository in to the root directory of your cloned git repository. Verify that the following modules are specified:

    "cors": "^2.8.5",
    "cookie-parser": "^1.4.5",
    "express-session": "^1.17.1",
    "jsonwebtoken": "^8.5.1",
    "passport": "^0.4.1",
    "passport-google-oauth20": "^2.0.0"
    
  3. Copy the server.js file from my git repository to the root directory. Then, update the server.js file to leverage the new modules. Update these lines to specify your clientID, clientSecret, and callbackURL to fit to your application URL.

    passport.use(new GoogleStrategy({
     clientID: 'FILLITWITHYOURVALUE.apps.googleusercontent.com',
     clientSecret: ' FILLITWITHYOURVALUE ',
     callbackURL: "https:///auth/google/callback"
    },
    
  4. Push your changes to these two files using the git commands like before (git add, git commit, and git push) and wait for the CI/CD pipeline to finish.

  5. Test your changes to protect the site by calling your application URL extended with the new established paths.

    a. Start the authentication: https://<yourNodeAppUrl>/auth/google b. Review the retrieved user profile from Google: https:// <yourNodeAppUrl>/profile

Step 5: Add more pages to the website

Now that we have the authentication set up, we can add more pages to the website to include a landing page and protected pages in a subdirectory. In this example, we will add a protected user profile page to display the data about the user we retrieved from Google during the authentication flow.

You can access these pages in my GitHub repo for this tutorial.

  1. Update the index.html in the views directory. If you want to, you can modify it for your application.

  2. Create a protected folder in your cloned git repository on the local development system. Copy the userProfile.html page to the protected folder. Review the code, and make sure to update the urls to match your URL for your application.

After you create those pages and commit and push the changes to git, and after the build pipeline processes the changes, you can view the pages by using the application URL. The landing page (index.html) includes the link to the protected page (userProfile.html). Because we configured Passport and Node.js to protect all files in the /protected directory structure, you will not be able to access the user profile page without authentication.

To keep the userProfile.html simple, it works with the session-store and uses some easy JQuery API calls to retrieve the user information from the Node.js server and its session storage.

Summary and next steps

In this tutorial, you learned how to work with IBM Cloud to create a Node.js application and establish a build automation to update it each time the git repository receives a push of new code. Furthermore, your application has been secured and leverages a well-known module for OpenID Connect authentication.

You might choose to extend this simple application for your needs. Perhaps you can build a more robust front-end using React, or create some additional back-end logic using Node-RED. Explore the tutorials and code patterns on IBM Developer for more ideas!

Acknowledgements

Special thank you to David Winter for helping me in the initial stages of this project.