プラグインAPIの新しいOAuthコード認可フロー

25Bから、Oracle Fusion Field Servicesでは、プラグインAPIに新しいOAuthコード認可フローが導入されています。

仕組み
プラグインAPIの新しいgetAuthorizationCodeプロシージャでは、アイデンティティ・プロバイダを使用してOracle Fusion Field Serviceですでに認証されているユーザーのセッションを使用して、JWT (アクセス・トークン)を取得できます。 JWTアクセス・トークンを使用して、アイデンティティ・プロバイダのREST APIに対して認証し、ユーザー権限の確認、ユーザーによるデータ更新の追跡などの必要なアクションを実行する必要があります。
フローについては、ここで説明します:

  • OAuthコード認可フローをサポートするアイデンティティ・プロバイダでアプリケーションを構成します。
  • クライアントID、スコープ、アイデンティティ・プロバイダ・エンドポイントなどの資格証明を使用して、アイデンティティ・プロバイダ・コード認可エンドポイントのURLを生成します。
  • プロシージャ・パラメータでこのURLを使用して、プラグインからgetAuthorizationCodeプロシージャをコールします。
  • プロシージャ・レスポンスで認可コードを取得します。
  • プラグインからこの認可コードによってJWTアクセス・トークンを取得します。
  • REST APIリクエスト認可でJWTアクセス・トークンを使用します。

ノート: JWTアクセス・トークンは、アプリケーションではなくユーザーのかわりに発行されます。

OAuthコード認可フロー

OAuthコード認可フロー

「ユースケース」
技術者は、作業オーダーの実行中にアラーム・システムを切断する必要があります。 このアクションは、企業のSSOアカウントを使用して実行する必要があり、監査目的で使用可能である必要があります。 アラームを切断し、このアクションに必要な説明を提供するプラグインを使用できます。

  • 技術者は、企業のSSOアカウントを使用してOracle Fusion Field Serviceにサインインします。
  • 技術者はプラグインを開き、企業のアイデンティティ・プロバイダからJWTトークンを取得します。
  • プラグインはトークンを使用して、企業IdPのREST APIをコールします。
  • IdPは、技術者のアイデンティティを検証します。
  • 技術者は、「プラグイン」画面のOracle Fusion Field Serviceのままです。

「プラグインAPIの変更点」
getAuthorizationCode
これは、25Bで導入された新しいプロシージャで、OAuth 2.0許可コード付与フローを使用してアクセス・トークン(JWT)を取得するために使用されます。 コードは、リソース・サーバーへのREST APIコールの認可に使用されるJWT (アクセス・トークン)を取得する必要があります。

プロシージャは1つの「必須」パラメータのみを受け入れます - URL. これは、OAuth 2.0許可コード付与フローによる許可を提供するアイデンティティ・プロバイダ・エンドポイントのURLです。 通常、URLにはサフィクス"/authorize"が含まれます。
URLは、次の表に示すように、いくつかの必須パラメータとオプション・パラメータで構成されます:

必須パラメータ

パラメータ 必須/オプション 摘要
REST APIエンドポイント 必須 OAuth 2.0認可コード・フローを提供します。 たとえば: https://idcs-instance.example.com/oauth2/v1/authorize
response_type=code  必須 認可コード・フローを指すパラメータ。
client_id  必須 OAuth 2.0認可コード・アプリケーションの作成時にアイデンティティ・プロバイダによって提供されるクライアントID。 たとえば: client_id=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
redirect_uri  必須 ユーザーがリダイレクトされるURL。 これはURLでエンコードされ、Oracle Fusion Field Service・インスタンス・ドメインと"/plugin-auth-redirect/"サフィクスで構成されます。 たとえば: &redirect_uri=https%3A%2F%2Fofs-instance.example.com%2Fplugin-auth-redirect%2F
scope 必須 承認のためにリクエストされたスコープ。 たとえば: '&scope=xxxx'. これは、OAuth 2.0認可コード・アプリケーション(アイデンティティ・プロバイダで構成)でサポートされているスコープのいずれかである必要があります。
コード交換のプルーフ・キー(PKCE)をサポートするためのオプションのパラメータ https://tools.ietf.org/html/rfc7636
code_challenge_method=S256 オプション

使用される暗号化メソッドのタイプ。

たとえば: code_challenge_method=S256. (値は"plain"ですが、その場合はコード検証とコード・チャレンジが等しい)

code_challenge  オプション

次のコード例で生成されるコード検証文字列のシグネチャ:

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);

}

コード検証文字列は、JWTを取得するためにリクエストで使用する必要があります。
state オプション これは、ユーザーがリダイレクトされるときに一部の情報を保持するために使用できます。 通常、このパラメータは、プロシージャがコールされる前にプラグインの現在の画面またはプラグイン内のナビゲーションに関するその他の情報を保持するために使用されます。

ノート: バージョン25B以降、初期化メッセージの生成元項目からOracle Fusion Field Service環境ドメインを導出できます。

リクエストの例

IDCSアイデンティティ・プロバイダへのプロシージャ・リクエストの例:

{
    "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

Microsoft Entraアイデンティティ・プロバイダへのプロシージャ・リクエストの例:

{

    "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"

    }

}

Microsoft Entraの認可コード・フローの構成に関するドキュメント - https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow

callProcedureResultメソッド - 成功、完了

レスポンスには次の3つのフィールドが含まれます:

  • redirectUrl (必須) - ユーザーをOracle Field Serviceにリダイレクトするために使用された完全なURL。
  • code (必須) - 認証コード。
  • state (オプション) - そのようなパラメータがredirectUrlに存在する場合は、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メソッド -成功、取消

新しいリクエストが開始され、新しいブラウザ・タブが開かれると、Oracle Fusion Field Serviceでユーザーのアクションをモニターできません。 このタブを閉じると、イベント通知は受信されません。 したがって、コードを取得するには、追加のリクエストを行う必要があります。 したがって、前のプロシージャ・コールは、「取消済」ステータスのcallProcedureResultを返します。

{    

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







callProcedureResultメソッド - エラー

返される可能性のあるエラー・メッセージの例:

{    

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










ビジネス上の利点

  • セキュリティの強化: OAuthコード許可付与フローでは、Oracle Fusion Field Serviceには、クライアント・シークレットなどのセキュアな資格証明は格納されません。 認可は、ユーザーをプラグインからアイデンティティ・プロバイダにリダイレクトしてからプラグインに戻すことで管理されます。
  • プラグインでの透過的なシングル・サインオン認証: SSO認証が必要なプラグインの場合、OAuthコード許可付与フローにより、ユーザーがアイデンティティ・プロバイダによって認証されます。 プラグインを開くと、リクエストがアイデンティティ・プロバイダに送信されます。 ユーザー・セッションがまだアクティブな場合、ユーザーはログイン資格証明を再入力しなくてもプラグインにリダイレクトされます。
  • SSO認証を必要とするプラグインの実装の簡略化: このメソッドにより、SSO認証が必要なプラグインを実装するプロセスが合理化されます。
  • 業界セキュリティ基準への準拠: 認可されたユーザーのみがアプリケーションおよびAPIにアクセスできるようにすることで、業界のセキュリティ標準を満たします。

有効化のステップ

この機能を有効化するうえで必要な操作はありません。

ヒントと考慮事項

Microsoft Azureのリクエストの例
MicrosoftからJWTおよびREST APIデータを取得するために使用できるフェッチ・リクエストの例を次に示します
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'
    }
});