Developing SaaS Extensions using VBCS and Helidon Micro-services Part 1

October 31, 2019 | 8 minute read
Angelo Santagata
Architect
Text Size 100%:

Introduction

This blog post details how you can develop a SaaS extension using VBCS and Helidon microservices and most importantly pass the user identity from the SaaS to the microservice so it can be used for data security etc.

In a previous blog post of mine I commented that whilst VBCS can be used directly against Oracle SaaS, and it works very well BTW, it is often recommended that you build a backend service to manage the interaction between SaaS and PaaS.  This can be done for a variety of reasons, e.g. combining multiple REST calls into a single REST call from the Server, using a cache like Redis or Coherence etc. When a developer decides on this approach they may find that one of the primary stumbling blocks is that they don’t know how to propagate identity between Oracle SaaS, VBCS and the REST Service.

This blog article leads the user through building a simple microservice, using the Helidon microservice, deploying the service to the Oracle Kubernetes Engine and then eventually consuming that service from within VBCS.

This blog article is split into these parts :

  • Configuring a new confidential oAuth application in IDCS

  • Testing the new confidential oAuth application using the postman tool

  • Creating configuring a Helidon Microservice which is secured using the IDCS oAuth microservice

In Part 2

  • Compiling and Deploying the Helidon application to Oracle Kubernetes Engine
  • Connecting to the Helidon MicroService from VBCS

Assumptions

  • The reader is familiar with Java and Java related technologies

  • The reader has deployed the helloworld (greeter) Helidon microservice locally

  • The reader has deployed sample applications to the Oracle Kubernetes Engine

  • The reader has the basic VBCS Skills and knows how to build a simple VBCS app and call a REST Service from within VBCS

Architecture

architecture

Associating VBCS with Oracle SaaS

One of the great advantages of using Oracle Visual Builder to extend Oracle SaaS is that you can have VBCS and Oracle SaaS associated so that they both use a single IDCS (IDentity Cloud Service) instance.   This means when you embed VBCS within a SaaS application and VBCS already knows who the user is. This is commonly known as single sign on and is important to ensure SaaS customizations as seamless as possible.

If your VBCS instance is not associated with Oracle SaaS you need to get the IDCS signing certificate imported into Fusion Applications and IDCS be added as a trusted issuer.

For more details see this solution document https://docs.oracle.com/en/solutions/extend-saas-with-java-cloud-service-apps/enable-oracle-fusion-applications-cloud-service-federation-and-oauth-trust-oracle-identity-cloud-ser1.html#GUID-53C8A800-3DC3-48F0-930E-11797185406B

 

Preparing IDCS to Accept a confidential oAuth Application

The magic link between VBCS and our Helidon based microservice will be a technology called oAuth. For our application to work we will need to setup an application in IDCS and configure it accordingly.
  • Within the IDCS console and select the hamburger icon () and select Applications. Every oAuth application requires an application to be configured within IDCS. 

  • Create an application of type “Confidential Application”, e.g. called “HelidonSAASEXtension”, then click next

  • Configure the application as a client and then set the following parameters :

Allowed Grant Types

Client Credentials
Resource Owner

Allow Non-HTTPs URLs

Checked ( this is only for dev and testing for production usage ensure https URLS are used

Click NEXT  but note we will come back to this screen later

  • Within Resources tab ensure the following parameters are set :

Primary Audience

http://localhost:8080/

(Ensure the primary audience has a trailing slash)

Add Scope

myapp

 

  • Go back to Client tab and add the scope you just added to the Resources section

  • Click Next to the end and Finish. 

  • IDCS will then present to you a ClientID and Client Secret, cut and paste these somewhere on your computer, although you can get them again afterwards if needed.

  • Now Activate the Application

  • Finally we need to make sure the JWK access signing certificate is available to non authenticated users.

  • Click the Hamburger icon() and select Menu Settings/Default Settings.

  • Make sure the “Access Signing Certificate” is selected. This allows the signing certificate to be obtained without logging into Oracle Identity Cloud Service

Before progressing to writing the Helidon java code, it is recommended we test out the new IDCS application settings to make sure they work. An excellent tool for doing this is the postman application (http://www.postman.com)

Within Postman create a new request :

  • Later on in this tutorial we will be building a Helidon Service and deploying it locally therefore lets enter http://localhost:8080/greet/whoami as the URL.

  • Within the Authorization tab select the type to be oAuth 2.0


  • Click the “Get New Access Token” button

  • Populate the fields accordingly

Token Name

Any name you want

Grant Type

Password Credentials

Access Token URL

https://<IDCS Hostname>.identity.oraclecloud.com/oauth2/v1/token

Get IDCS Hostname this from your browser where you configured the

Username

Your Username

Password

Your IDCS Password

Don’t worry these credentials are only used for testing, at runtime Helidon won’t be using these at all

Client ID

The Client ID displayed earlier

Client Secret

The Client Secret displayed earlier

Scope

http://localhost:8080/myapp

Client Authentication

Send as Basic Auth Header


  • Click the request token, if all works fine you should be displayed with a nice new token. If there is an error, check the postman error log for clues to what has gone wrong.

  • Scroll down and select the use token button, this copies the token to the request payload.

  • DON’T delete the request yet we’ll be using it later

Creating simple secure Helidon REST Service

Using the instructions on the Helidon website, create yourself a sample Helidon MP application (The greet application) and make sure it runs locally.

These instructions can be found here https://helidon.io/docs/latest/#/guides/03_quickstart-mp

Once this is done we can add our own REST Resource function to the application. Our goal here is to simply return the name of the user who called the function.  Now using your favourite IDE (Eclipse, InteliJ, vi etc) let’s add a REST Resource to the greet application.

Open the GreetResource.java application and add the following function to the GreetResource  java Class.

 

    @Path("/whoami")
    @GET
    @Authenticated
    @Produces(MediaType.APPLICATION_JSON)
    public Response whoAmI(@Context SecurityContext context)
    {
        String theUser= context.userName();
        System.out.println("Who Am I has been called as user "+theUser);
        JsonObject res=JSON.createObjectBuilder().add("username",theUser).build();
        return Response.ok().entity(res).header("Access-Control-Allow-Origin","*").build();
    }


Notes

Line

What does it do

1

Sets up the path

2

Signifies this is a GET request

3

Marks this request as an Authenticated request

4.

Method produces a JSON payload

9

Generates a JSON payload which contains an attribute called “username” with the value being the username that Helidon detects

10

Returns the data.
The header method here adds a CORS header which allows the method to be executed from anywhere

 

As noted above on line 10 we add a CORS header to the request, you may be wondering why we need this? This is so that we can call the microservice from a our VBCS app using a technique called “token relay”. This tells VBCS to call the microservice direct from the client (browser) and not via the VBCS server proxy. Doing this has the advantage of being slightly faster as the request does not need to go via the VBCS Server at run-time.

Our application now implements all the security stuff in code but the Helidon isn’t configured to introspect the security tokens properly at runtime. If you were to execute this code you would probably get a 401 Unauthorised because whilst Helidon knows it’s a protected resource (due to the @Authenticated annotation) but it doesn’t know how to validate it.

Helidon supports a number of security providers which you can use to authenticate the user, they are all documented here https://helidon.io/docs/latest/#/security/02_providers. For our use case we will be using the rather straightforward and simple JWT provider. The JWT Provider implements authentication by validating the JWT token passed along in the Authorization header.

Add a file called application.yaml in the resources directory with the following contents. Be careful with formatting as this file is a YAML file and spaces matter.


security:
  config.require-encryption: false
  properties:
  providers:
    - jwt:
        atn-token:
          jwk-url: "https://idcs-aaaaabbbbbbcccccdddd1111222333.identity.oraclecloud.com/admin/v1/SigningCert/jwk"
          jwt-audience: "http://localhost:8080/"
          verify-signature : true
        # just need to define this, so an outbound target is found
        sign-token:
          outbound:
            - name: "all-services"

Important notes here are :

  • The jwk-url is pointing to your IDCS instance, ensure the hostname is set correctly
  • The verify-signature parameter is asking the helidon layer to check the signature matches the IDCS signature. You can set this to false for testing  different users without validating the signature during development.

 

Now compile and run your microservice with the following command

mvn clean package exe:java

If all goes well the above command will compile and run the helidon microservice. You should see something like this

 

Testing the Microservice

We will again use the postman tool to test the service. Using the request definition defined earlier go and request another token (using the Get New Access Token button + Use Token) and then press the send button. If all goes well the request will call the microservice, validate the token against IDCS, then execute the whoAmI() method and return the username to postman.

Deploying 

Conclusion

So far we have demonstrated how you configure IDCS and then create a Helidon Microservice which is protected, and authenticated , by a IDCS confidential application. In the next blog post we will deploy this function to the cloud , the Oracle Containers Engine, and then build a VBCS UI which consumes it – all of this will be one propagating the users identity throughout the layers.

In Part 2 we will be taking what we have  built here and deploying it to the Oracle Container Engine (aka Oracle Kubernetes Engine) and then we will build a VBCS User Interface to consume the REST Service..

 

 

 

Angelo Santagata

Architect

25+ years of Oracle experience, specialising in Technical design and design authority of Oracle Technology solutions, specialising in integrating technology with Oracles SaaS products.

Extensive credible communication skills at all levels, from hard core developers to C-Level executives.

Specialities: Oracle Fusion Apps Integration, Oracle Cloud products, SaaS Integration architectures, Engaging with SIs & ISVs, Technical Enablement, Customer Design Reviews,  advisory and project coaching.

TOGAF 9 Architect and Oracle Cloud Infrastructure Architect Certified


Previous Post

Decorrelating ODI and GoldenGate for Integrated Changed Data Capture

Christophe Dupupet | 4 min read

Next Post


Connect from Windows VPN Client to the VPN RA Libreswan on OCI

Catalin Andrei | 3 min read