Orchestration of third-party services using OAuth 2.0 authentication

This document describes the example of how you can implement and configure a workflow that orchestrates the interaction with an OAuth 2.0 secured REST service.

For more information about orchestrating and configuring OpenAPI services, see Orchestrating the OpenAPI services, Configuring the OpenAPI services endpoints, and Authentication for OpenAPI services in SonataFlow.

Example of OAuth 2.0 orchestration in a workflow

To understand the example of OAuth 2.0 orchestration in a workflow, you can use the serverless-workflow-oauth2-orchestration-quarkus example application. This example application implements a workflow related to currency exchange calculations, which orchestrates an OAuth 2.0 secured REST service provided by Acme Financial Services.

Suppose you have a set of applications that must resolve the currency exchange calculations as their regular operations, and to resolve the currency exchange calculations, you need to get the accurate exchange rates. For this purpose, you can use the Acme Financial Services.

When you use the Acme Financial Services, you can query the exchange rates using their OAuth 2.0 secured services, which you can access using the granted credentials. However, you do not want to expose the services provided by Acme to the applications. In this case, you can implement a workflow that resolves the following aspects:

Orchestration with services provided by Acme and currency exchange calculations.
Authentication requirements to access the services provided by Acme.
Potential vendor lock-in problems, in case you want to change the provider in the future.
Domain-specific validations and optimizations.

The further sections describes how an end-to-end solution is created in the serverless-workflow-oauth2-orchestration-quarkus example application. To see the source code of serverless-workflow-oauth2-orchestration-quarkus example application, you can clone the incubator-kie-kogito-examples repository in GitHub and select the serverless-workflow-examples/serverless-workflow-oauth2-orchestration-quarkus directory.

The serverless-workflow-oauth2-orchestration-quarkus example application contains the following services to compose the solution:

currency-exchange-workflow: Workflow that implements the currency exchange calculations.
acme-financial-service: REST service that provides the exchange rates.
acme-oauth2-server: Keycloak server that secures the REST services from Acme Financial Services.

The following figure describes the architecture of the solution in serverless-workflow-oauth2-orchestration-quarkus example application:

Figure 1. Example architecture diagram of the solution

The application creates a workflow instance to calculate the currency exchange.
The workflow executes an OpenAPI operation to get the exchange rates information.
Authorizations are produced to validate the access.
The workflow receives the exchange rates information and executes the calculations.
The execution of workflow is finalized by sending the result to the application.

The workflow automatically manages the interactions with the OAuth 2.0 server. Also, you must configure a Quarkus OpenId Connect Client (OIDC). For more information, see Configuration in serverless-workflow-oauth2-orchestration-quarkus example application.

currency-exchange-workflow

The currency-exchange-workflow in serverless-workflow-oauth2-orchestration-quarkus example application is a workflow that implements the currency exchange calculations.

The following figure describes the workflow in currency-exchange-workflow:

Figure 2. Example currency-exchange-workflow

First, validate the input data.
Check the validation results:
1. If validation is successful, then transition to (3).
2. If validation is unsuccessful, then no transition and finalize the workflow with the error execution status.
Send REST request to acme-financial-service to retrieve the exchange rates:
1. If the request is successful, then transition to (4).
2. If the request is unsuccessful, then transition to (6).
Calculate the currency exchange and transition to (5).
Set the successful execution status and finalize the currency-exchange-workflow execution.
Set the error execution status and finalize the currency-exchange-workflow execution.

The following currency-exchange-workflow.sw.json file shows the specification of the currency-exchange-workflow:

currency-exchange-workflow.sw.json file

{
  "id": "currency_exchange_workflow",
  "version": "1.0",
  "name": "Currency Exchange SW",
  "dataInputSchema": "currency-exchange-workflow-schema.json",
  "start": "ValidateInputs",
  "functions": [
    {
      "name": "validateInputs",
      "type": "custom",
      "operation": "service:org.kie.kogito.examples.ExchangeWorkflowHelper::validateInputs"
    },
    {
      "name": "getExchangeRate",
      "type": "rest",
      "operation": "specs/acme-financial-service.yml#exchangeRate"
    },
    {
      "name": "calculateExchange",
      "type": "expression",
      "operation": "${ { calculateExchangeResult: .amount * .exchangeRate } }"
    }
  ],
  "errors": [
    {
      "name": "service_error",
      "code": "java.lang.Exception"
    }
  ],
  "states": [
    {
      "name": "ValidateInputs", (1)
      "type": "operation",
      "actions": [
        {
          "name": "validateInputsAction",
          "functionRef": {
            "refName": "validateInputs",
            "arguments": {
              "currencyFrom": "${ .currencyFrom }",
              "currencyTo": "${ .currencyTo }",
              "amount": "${ .amount }",
              "exchangeDate": "${ .exchangeDate }"
            }
          }
        }
      ],
      "transition": "CheckValidation"
    },
    {
      "name": "CheckValidation", (2)
      "type": "switch",
      "dataConditions": [
        {
          "condition": "${ .executionStatus == \"ERROR\" }",
          "end": true
        }
      ],
      "defaultCondition": {
        "transition": "GetExchangeRate"
      }
    },
    {
      "name": "GetExchangeRate", (3)
      "type": "operation",
      "actions": [
        {
          "name": "getExchangeRateAction",
          "functionRef": {
            "refName": "getExchangeRate",
            "arguments": {
              "currencyFrom": "${ .currencyFrom }",
              "currencyTo": "${ .currencyTo }",
              "exchangeDate": "${ .exchangeDate }"
            }
          },
          "actionDataFilter": {
            "results": "${ {exchangeRate: .rate} }"
          }
        }
      ],
      "transition": "CalculateExchange",
      "onErrors": [
        {
          "errorRef": "service_error",
          "transition": "EndWithError"
        }
      ]
    },
    {
      "name": "CalculateExchange", (4)
      "type": "operation",
      "actions": [
        {
          "name": "calculateExchangeAction",
          "functionRef": {
            "refName": "calculateExchange"
          },
          "actionDataFilter": {
            "results": "${ {result: .calculateExchangeResult} }"
          }
        }
      ],
      "transition": "EndSuccessful"
    },
    {
      "name": "EndWithError", (5)
      "type": "inject",
      "data": {
        "executionStatus": "ERROR",
        "executionStatusMessage": "Execution failed: The acme-financial-service invocation has failed, check that the service is running and that you have configured the OAuth2 client properly"
      },
      "end": true
    },
    {
      "name": "EndSuccessful", (6)
      "type": "inject",
      "data": {
        "executionStatus": "OK",
        "executionStatusMessage": "Execution successful"
      },
      "end": true
    }
  ]
}

1	`ValidateInputs` state executes the `validateInputs` function to validate the input data.
2	`CheckValidation` state determines the next state to go by evaluating the validation results.
3	`GetExchangeRate` state executes the `getExchangeRate` function to retrieve the exchange rate from the remote server.
4	`CalculateExchange` state executes the `calculateExchange` function to calculate the currency exchange.
5	`EndWithError` state finalizes the workflow with an `ERROR`.
6	`EndSuccessful` state finalizes the workflow with successful `OK` status.

The validateInputs function is used to execute the custom Java processing as part of the workflow. For more information about custom functions, see Serverless Workflow specification.

The following is an example of validateInputs function definition:

Example validateInputs function definition

{
  "name": "validateInputs", (1)
  "type": "custom", (2)
  "operation": "service:org.kie.kogito.examples.ExchangeWorkflowHelper::validateInputs" (3)
}

1	`validateInputs` function declaration.
2	`custom` type that enables you to use your own Java class to implement a function.
3	Specifies that the function is implemented by the method `validateIntpus` in the `org.kie.kogito.examples.ExchangeWorkflowHelper` Java class.

To implement a custom function, you must create a Java class such as ExchangeWorkflowHelper in your project:

Example ExchangeWorkflowHelper.java file

package org.kie.kogito.examples;

import javax.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class ExchangeWorkflowHelper {

    public ValidationResult validateInputs(String currencyFrom,
                                           String currencyTo,
                                           double amount,
                                           String exchangeDate) {
        // Implement your custom Java processing here and return
        // a Java POJO to the Serverless Workflow.
        if (!good) {
            return new ValidationResult("ERROR", "Not good!");
        }
        return new ValidationResult();
    }

    public static class ValidationResult {
        private String executionStatus;
        private String executionStatusMessage;
        // getters, setters, etc.
    }
}

To access the acme-financial-service REST service in currency-exchange-workflow, a workflow function such as getExchangeRate is used. For more information about using functions for REST services, see Serverless Workflow specification.

Following is the function definition of getExchangeRate:

Example getExchangeRate function definition

{
  "name": "getExchangeRate", (1)
  "type": "rest",
  "operation": "specs/acme-financial-service.yml#exchangeRate" (2)
}

1	`getExchangeRate` function declaration.
2	Specifies that the function is implemented by the `exchangeRate` operation in the `acme-financial-service.yml` file.

For the previous configuration, the acme-financial-service.yml file must be located in the src/main/resources/specs directory of the project.

In order to filter the information, which must be returned to the currency-exchange-workflow, an actionDataFilter is used:

Example actionDataFilter to pass the getExchangeRate results

  "actionDataFilter": {
    "results": "${ {exchangeRate: .rate} }" (1)
  }

1	Merge the value of the `rate` property to the `exchangeRate` workflow data property. The value of the `rate` property is retrieved from the `acme-financial-service` invocation result.

For more information about action data filters, see Action data filters in Serverless Workflow specification.

To calculate the currency exchange rates in currency-exchange-workflow, a function named calculateExchange is used:

Example calculateExchange function definition

{
  "name": "calculateExchange", (1)
  "type": "expression", (2)
  "operation": "${ { calculateExchangeResult: .amount * .exchangeRate } }" (3)
}

1	`calculateExchange` function declaration.
2	`expression` type that enables you to use an expression to implement a function.
3	Specifies that the function returns a JSON object with a `calculateExchangeResult` property, containing the calculation.

For more information about using functions for expression evaluation, see Serverless Workflow specification.

Similar to getExchangeRate to filter the information, which must be returned to the currency-exchange-workflow, an actionDataFilter is used:

Example actionDataFilter to pass the calculateExchange results:

  "actionDataFilter": {
    "results": "${ {result: .calculateExchangeResult} }" (1)
  }

1	Merge the value of the `calculateExchangeResult` property to the `result` workflow data property. The value of the `calculateExchangeResult` property is retrieved from the expression result.

acme-financial-service

The acme-financial-service in serverless-workflow-oauth2-orchestration-quarkus example application is a REST service that provides the exchange rates. Following is the OpenAPI specification that defines the acme-financial-service:

Example acme-financial-service.yml OpenAPI specification

---
openapi: 3.0.3
info:
  title: Acme Financial Service API
  version: 1.0.1
paths:
  /financial-service/exchange-rate: (1)
    get:
      tags:
        - Acme Financial Resource
      operationId: exchangeRate
      parameters: (2)
        - name: currencyFrom
          in: query
          schema:
            type: string
        - name: currencyTo
          in: query
          schema:
            type: string
        - name: exchangeDate
          in: query
          schema:
            type: string
      responses: (3)
        "200":
          description: OK
          content: (4)
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeRateResult'
      security:
        - acme-financial-oauth: [ ] (5)
components:
  schemas:
    ExchangeRateResult: (6)
      type: object
      properties:
        rate:
          format: double
          type: number
  securitySchemes:
    acme-financial-oauth: (7)
      type: oauth2 (8)
      flows:
        clientCredentials: (9)
          authorizationUrl: http://localhost:8281/auth/realms/kogito/protocol/openid-connect/auth
          tokenUrl: http://localhost:8281/auth/realms/kogito/protocol/openid-connect/token
          scopes: { }

1	REST path to access the `exchangeRate` operation in the remote server.
2	Parameter of the `exchangeRate` operation.
3	Responses of the `exchangeRate` operation.
4	Response type and data exchange format.
5	Specifies that the `exchangeRate` operation is secured using the `acme-financial-oauth` security scheme.
6	Response type specification.
7	Specification of the `acme-financial-oauth` security scheme.
8	Security scheme type. The security scheme type indicates that you must configure a Quarkus OpenId Connect Client (OIDC) using `acme_financial_oauth` name to execute the operation.
9	Authentication flow and related information.

For more information about the acme-financial-service implementation, see acme-financial-service in serverless-workflow-oauth2-orchestration-quarkus example application.

Configuration in `serverless-workflow-oauth2-orchestration-quarkus` example application

The configuration for the workflow used in serverless-workflow-oauth2-orchestration-quarkus example application includes defining required properties in application.properties file as shown in the following example:

Example application.properties file configuration

quarkus.openapi-generator.codegen.spec.acme_financial_service_yml.base-package=com.acme (1)

quarkus.rest-client.acme_financial_service_yml.url=http://localhost:8483 (2)

quarkus.oidc-client.acme_financial_oauth.discovery-enabled=false (3)
quarkus.oidc-client.acme_financial_oauth.auth-server-url=http://localhost:8281/auth/realms/kogito/protocol/openid-connect/auth (4)
quarkus.oidc-client.acme_financial_oauth.token-path=http://localhost:8281/auth/realms/kogito/protocol/openid-connect/token (5)
quarkus.oidc-client.acme_financial_oauth.client-id=kogito-app (6)
quarkus.oidc-client.acme_financial_oauth.grant.type=client
quarkus.oidc-client.acme_financial_oauth.credentials.client-secret.method=basic (7)
quarkus.oidc-client.acme_financial_oauth.credentials.client-secret.value=secret (8)

1	Package name for automatically generated classes that implement the access to all operations defined in the `acme-financial-service.yml` file.
2	Root URL to access all operations defined in the `acme-financial-service.yml` file. For the `exchangeRate` operation, a URL such as `http://localhost:8483/financial-service/exchange-rate` is automatically generated.
3	Disables the OAuth 2.0 server endpoints discovery as the endpoints provided in the `acme-financial-service-yml` file are used instead.
4	Authentication URL of the OAuth 2.0 server.
5	Relative path or URL of the OAuth 2.0 token endpoint, which allocates access and refreshes tokens.
6	Client ID to identify the workflow against the authorization service, such as `kogito-app`. This identifier must be provided by Acme.
7	Method that is used at the time of sending the `client-secret` for the authentications when the client grant type is used.
8	`client-secret` to authenticate the workflow against the authorization service when the client grant type is used. This secret must be provided by Acme.

To configure the Quarkus OpenId Connect Client (OIDC) for acme_financial_service_oauth service, you must follow the rules described in Example of OAuth 2.0 authentication.

Also, the particular attributes depend on the OAuth 2.0 server and authorization flow to use. You can get the information about the OAuth 2.0 server and authorization flow from the acme-financial-service.yml file.

Also, you can use the alternatives defined in the Quarkus configuration reference guide to configure the properties in application.properties file. You can define environment variables to set the authentication secrets, and you can use the Quarkus Credentials Provider framework.

Running the example application

Once you clone the serverless-workflow-oauth2-orchestration-quarkus example application from GitHub repository, you can run the example application.

Prerequisites

Java 17+ is installed.
Maven 3.9.3 or later is installed.
Docker 20.10.7 or later is installed.
(Optional) Docker compose 1.27.2 or later is installed.

Procedure

In a command terminal, clone the incubator-kie-kogito-examples repository and navigate to the cloned directory:
Clone incubator-kie-kogito-examples repository and navigate to the directory
git clone https://github.com/apache/incubator-kie-kogito-examples.git cd incubator-kie-kogito-examples/serverless-workflow-examples/serverless-workflow-oauth2-orchestration-quarkus
Run the following command to build the example application using Apache Maven:
Build the example application
mvn clean install

In a separate command terminal window, start the Keycloak server:

Start the Keycloak server

cd {kie_kogito_examples_repo_name}/serverless-workflow-examples/serverless-workflow-oauth2-orchestration-quarkus/scripts

./startKeycloak.sh

Alternatively, you can start the Docker Compose using the following command:

Start Docker Compose

cd {kie_kogito_examples_repo_name}/serverless-workflow-examples/serverless-workflow-oauth2-orchestration-quarkus/docker-compose

docker-compose up

In a separate command terminal window, navigate to the acme-financial-service directory and start the Quarkus application of Acme Financial Service:

Start Acme Financial Service

cd {kie_kogito_examples_repo_name}/serverless-workflow-examples/serverless-workflow-oauth2-orchestration-quarkus/acme-financial-service

java -jar target/quarkus-app/quarkus-run.jar

In a separate command terminal window, navigate to the currency-exchange-workflow directory and start the Quarkus application of currency exchange workflow:
Start currency exchange workflow
cd {kie_kogito_examples_repo_name}/serverless-workflow-examples/serverless-workflow-oauth2-orchestration-quarkus/currency-exchange-workflow java -jar target/quarkus-app/quarkus-run.jar

When all the services are running, use the following curl commands to run the currency-exchange-workflow:

The following is an example of successful execution when calculating the currency exchange from EUR to USD:

Example request
Example response

curl -X 'POST' \
  'http://localhost:8080/currency_exchange_workflow' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
       "currencyFrom": "EUR",
       "currencyTo": "USD",
       "exchangeDate": "2022-06-10",
       "amount": 2.0
    }'

{
  "id": "399ce304-037c-486d-b4bf-1564baf907a1",
  "workflowdata": {
    "currencyFrom": "EUR",
    "currencyTo": "USD",
    "exchangeDate": "2022-06-10",
    "amount": 2.0,
    "executionStatus": "OK",
    "executionStatusMessage": "Execution successful",
    "exchangeRate": 1.0578,
    "result": 2.1156
  }
}

The following is an example of an unsupported currency error when calculating the currency exchange from EUR to MXN:

Example request
Example response

curl -X 'POST' \
  'http://localhost:8080/currency_exchange_workflow' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "currencyFrom": "EUR",
    "currencyTo": "MXN",
    "exchangeDate": "2022-06-10",
    "amount": 2.0
}'

{
  "id": "e0e7708d-c82c-47d7-9354-09ccd1e972bb",
  "workflowdata": {
    "currencyFrom": "EUR",
    "currencyTo": "MXN",
    "exchangeDate": "2022-06-10",
    "amount": 2,
    "executionStatus": "ERROR",
    "executionStatusMessage": "Invalid currencyTo: MXN, only the following currencies are supported [EUR, USD, JPY, GBP, CAD, BRL, AUD]",
    "exchangeRate": null
  }
}

In the previous examples, the currencies supported by the currency-exchange-workflow include EUR, USD, JPY, GBP, CAD, BRL, and AUD. However, the acme-financial-service REST service can resolve any type of currency exchange. This is an example of a workflow implementing the intermediate data filtering, transforming, and validations.

The following is an example of the occurrence of unexpected errors when accessing acme-financial-service:

Before you launch the command, you must go to the terminal window where you started the acme-financial-service and stop the service using CTRL+C.

Example request
Example response

curl -X 'POST' \
  'http://localhost:8080/currency_exchange_workflow' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "currencyFrom": "EUR",
    "currencyTo": "USD",
    "exchangeDate": "2022-06-10",
    "amount": 2.0
}'

{
  "id": "0044ffa0-7b2b-4fdc-af60-cd98c6bd3ade",
  "workflowdata": {
    "currencyFrom": "EUR",
    "currencyTo": "USD",
    "exchangeDate": "2022-06-10",
    "amount": 2.0,
    "executionStatus": "ERROR",
    "executionStatusMessage": "Execution failed: The acme-financial-service invocation has failed, check that the service is running and that you have configured the OAuth2 client properly",
    "exchangeRate": null
  }
}

In this example the error indicates that it was not possible to contact the acme-financial-service.

Additional resources

Orchestrating the OpenAPI services

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!

Orchestration of third-party services using OAuth 2.0 authentication

Example of OAuth 2.0 orchestration in a workflow

Configuration in serverless-workflow-oauth2-orchestration-quarkus example application

Running the example application

Additional resources

Found an issue?

Configuration in `serverless-workflow-oauth2-orchestration-quarkus` example application