New OAuth Code Authorization Flow in Plugin API

Effective from 25B, Oracle Fusion Field Services introduces the new OAuth Code Authorization flow in Plugin API.

How it works?
The new getAuthorizationCode procedure of Plugin API provides the ability to obtain a JWT (access token) using a session of a user already authenticated in Oracle Fusion Field Service using an Identity Provider. Using the JWT access token you'll have to authenticate to the REST API of your Identity Provider to perform required actions such as check user permissions, track data updates made by the user, and so on.
The flow is described here:

  • Configure an application on an Identity Provider that supports the OAuth Code Authorization Flow.
  • Use credentials such as Client ID, Scope, and Identity Provider endpoint to generate the URL to the Identity Provider Code Authorization endpoint.
  • Call the "getAuthorizationCode" procedure from the plugin with this URL in the procedure parameters.
  • Obtain an authorization code in the procedure response.
  • Obtain a JWT access token by this authorization code from the plugin.
  • Use the JWT access token in the REST API request authorization.

The JWT access token is issued on behalf of a user rather than an application.

OAuth Code Authorization Flow

OAuth Code Authorization Flow

Use case
A technician needs to disconnect an alarm system while performing a work order. This action must be performed using the corporate SSO account and should be available for audit purposes. A plugin is available to disconnect the alarm and provide the necessary clarification for this action.

  • The technician signs into Oracle Fusion Field Service using the corporate SSO account.
  • The technician opens the plugin, which retrieves a JWT token from the corporate Identity provider.
  • The plugin uses the token to call the REST API of the corporate IdP.
  • The IdP verifies the technician's identity.
  • The technician remains in Oracle Fusion Field Service on the Plugin screen.

Changes in Plugin API
getAuthorizationCode 
This is a new procedure introduced in 25B and is used to obtain an Access token (JWT) using the OAuth 2.0 Authorization Code Grant flow. The code needs to obtain a JWT (access token) which is used to authorize to the REST API calls to the Resource Server. 

The procedure accepts only one mandatory parameter - URL. This is the URL of the Identity Provider endpoint which provides authorization by OAuth 2.0 Authorization Code Grant Flow. Usually the URL contains the "/authorize" suffix. 
The URL consists of several required and optional parameters as shown in the below table:

Required Parameters

Parameters Required/Optional Description
REST API Endpoint Required Provides OAuth 2.0 Authorization Code Flow. For example:  https://idcs-instance.example.com/oauth2/v1/authorize
response_type=code  Required The parameter that points an Authorization Code Flow.
client_id  Required The Client ID, provided by Identity Provider during the creation of OAuth 2.0 Authorization Code application. For example: client_id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
redirect_uri  Required The URL to which the user will be redirected. It is URL encoded and consists of Oracle Fusion Field Service instance domain and "/plugin-auth-redirect/" suffix. For example: &redirect_uri=https%3A%2F%2Fofs-instance.example.com%2Fplugin-auth-redirect%2F
scope  Required The scope requested for authorization. For example:  '&scope=xxxx'. It should be one of the scopes that is supported by OAuth 2.0 Authorization Code application (configured on Identity Provider). 
Optional parameters, to support Proof Key for Code Exchange (PKCE)   https://tools.ietf.org/html/rfc7636
code_challenge_method=S256 Optional

Type of encryption method used.

For example: code_challenge_method=S256.  (The value could be "plain" but in that case Code Verifier and Code Challenge is equal)
code_challenge  Optional

The signature of the Code Verifier string that is generated by the following code example:

async function generateCodeChallenge(codeVerifier) {

    const encoder = new TextEncoder();

    const data = encoder.encode(codeVerifier);

    const digest = await crypto.subtle.digest('SHA-256', data);

 

    return base64UrlEncode(digest);

}

The Code Verifier string should be used in the request to obtain JWT.
state  Optional This can be used to keep some information when user will be redirected. Usually, the parameter is used to keep the information of Plugin's current screen or some other information of navigation inside the plugin before the procedure had been called. 

Starting with version 25B, the Oracle Fusion Field Service environment domain can be derived from the origin item in the initialization message.

Request examples

The example of the procedure request to IDCS Identity Provider:

{
    "apiVersion": 1,
    "method": "callProcedure",
    "procedure": "getAuthorizationCode",
    "callId": "1111111111",
    "params": {
        "url": "https://idcs-instance.example.com/oauth2/v1/authorize
?response_type=code
&client_id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
&redirect_uri=https%3A%2F%2Fofs-instance.example.com%2Fplugin-auth-redirect%2F
&scope=urn: opc:resource:faaas:fa:XXXXXXXXX-XXXXurn:opc:resource:consumer::all"
    }
}

The documentation of configuration of Authorization Code Flow in IDCS - https://docs.oracle.com/en-us/iaas/Content/Identity/api-getstarted/AuthCodeGT.htm

The example of the procedure request to Microsoft Entra Identity Provider:

{

    "apiVersion": 1,

    "method": "callProcedure",

    "procedure": "getAuthorizationCode",

    "callId": "1111111111",

    "params": {

        "url": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize

?response_type=code

&client_id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

&redirect_uri=https%3A%2F%2Fofs-instance.example.com%2Fplugin-auth-redirect%2F

&scope=User.Read

&code_challenge_method=S256

&code_challenge=VmLy6wpzYdHI99H0yeP64qEAyjJL_gu915gJUplobBA"

    }

}

The documentation of configuration of Authorization Code Flow in Microsoft Entra - https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow

callProcedureResult method - success, completed

The response contains three fields:

  • redirectUrl (mandatory) - the full URL which was used to redirect user to Oracle Field Service.
  • code (mandatory) - the authorization code.
  • state (optional) - if such parameter is present in redirectUrl it will be returned separately, just to make easier to get it, without parsing the redirectUrl.

{    

    "apiVersion": 1,
    "method": "callProcedureResult",
    "callId": "1111111111",
    "procedure": "getAuthorizationCode",
    "resultData": {
        "result": "completed",
        "code": "xxxxx",
        "redirectUri": "https://ofs-instance.example.com/plugin-auth-redirect/?code=xxxxxx&some_other_return_param=xxxxx",
        "state": "some_state"
    }
}
 










callProcedureResult method - success, cancelled

When a new request is initiated, and a new browser tab is opened, Oracle Fusion Field Service cannot monitor the user's actions. If this tab is closed, it won't receive an event notification. Therefore, to obtain the code, an additional request must be made. Consequently, the previous procedure call will return a callProcedureResult with a cancelled status.

{    

    "apiVersion": 1,
    "method": "callProcedureResult",
    "callId": "1111111111",
    "procedure": "getAuthorizationCode",
    "resultData": {
        "result": "cancelled",
        "reason": "SAME_PROCEDURE_NEW_CALL_BEFORE_COMPLETION"
    }
}







callProcedureResult method - error

The example of the error messages that could be returned:

{    

    "apiVersion": 1,
            "method": "error",
            "errors": [
                {
                    "type": "TYPE_PROCEDURE_ERROR",
                    "code": "CODE_UNKNOWN",
                    "procedure": "getAuthorizationCode", <---- the field persists starting from 25b
                    "data": "Authorization Code obtaining is rejected. The mandatory parameter \"code\" is absent in redirect URI: https://ofs-instance.example.com/plugin-auth-redirect/?error=invalid_request&error_description=Client+xxxx+provided+an+invalid+response+mode%3A+query."
                }
            ],
            "callId": "xxxx"
}










{    

    "apiVersion": 1,
    "method": "error",

    "errors": [

        {

            "type": "TYPE_PROCEDURE_ERROR",

            "code": "CODE_PROCEDURE_UNAVAILABLE",
            "procedure": "getAuthorizationCode" <---- the field persists starting from 25b

        }

    ],
}

The example of fetch requests that could be used to get JWT and REST API data from Microsoft:

fetch('https://login.microsoftonline.com/xxxx/oauth2/v2.0/token', {
    headers: {
        "content-type": "application/x-www-form-urlencoded; charset=UTF-8",
    },
    method: "POST",
    body: 'client_id=xxxx&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fofs-instance.example.com%2Fplugin-auth-redirect%2F&code=xxxx'
});
fetch("https://graph.microsoft.com/v1.0/me", {
    headers: {
        authorization: 'Bearer xxxx'
    }
});










Business Benefit

  • Enhanced Security: With the OAuth Code Authorization Grant Flow, Oracle Fusion Field Service does not store any secure credentials, such as the Client Secret. Authorization is managed by redirecting the user from the plugin to the Identity Provider and then back to the plugin.
  • Transparent Single Sign-On Authentication in Plugins: For plugins requiring SSO authentication, the OAuth Code Authorization Grant Flow ensures users are authenticated by an Identity Provider. When a plugin is opened, a request is sent to the Identity Provider. If the user session is still active, the user is redirected to the plugin without needing to re-enter their login credentials.
  • Simplified Implementation of Plugins Requiring SSO Authentication: This method streamlines the process of implementing plugins that need SSO authentication.
  • Compliance with Industry Security Standards: It meets industry security standards by ensuring that only authorized users have access to applications and APIs.

Steps to Enable

You don't need to do anything to enable this feature.

Tips And Considerations

Requests example for Microsoft Azure
The following example of fetch requests that could be used to get JWT and REST API data from Microsoft
fetch('https://login.microsoftonline.com/xxxx/oauth2/v2.0/token', {
    headers: {
        "content-type": "application/x-www-form-urlencoded; charset=UTF-8",
    },
    method: "POST",
    body: 'client_id=xxxx&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fofs-instance.example.com%2Fplugin-auth-redirect%2F&code=xxxx'
});
fetch("https://graph.microsoft.com/v1.0/me", {
    headers: {
        authorization: 'Bearer xxxx'
    }
});