1. Mobile Plugin Framework
  2. getAuthorizationCode

getAuthorizationCode

OAuth Code Authorization Flow in Plugin API

The OAuth Code Authorization flow in the Plugin API enables the acquisition of a JWT (access token) by using an already authenticated user session in Oracle Fusion Field Service through an Identity Provider. With the JWT access token, you must authenticate to the REST API of your Identity Provider to execute necessary actions, such as verifying user permissions, tracking data updates made by the user, and so forth.

The flow is detailed 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.
Note: The JWT access token is issued on behalf of a user rather than an application.
This flowchart shows the OAuth Code Authorization Flow in Plugin API:
This flowchart shows the OAuth Code Authorization Flow in Plugin API.

getAuthorizationCode Procedure

The getAuthorizationCode procedure 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 REST API calls to the Resource Server.

Procedure Overview

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.

Parameters

The URL consists of several parameters as shown in the table:

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 to the 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 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 The 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.
Note: Oracle Fusion Field Service environment domain can be taken from the 'origin' item of the init message.
Example of a Request
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 Fusion 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

This occurs when a new request is made. Once a new browser tab is opened, Oracle Field Service cannot track the user's actions and won't receive an event if the tab is closed. Therefore, the only way to obtain the code is by making an additional request. In this scenario, the previous procedure call will return a "callProcedureResult" with a "cancelled" result.

{    

    "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", "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 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'
    }
});