[Cloud] Accessing Oracle Process Cloud Service REST API using OAuth

原文はこちら。
https://community.oracle.com/community/cloud_computing/oracle-cloud-developer-solutions/blog/2017/02/19/accessing-oracle-process-cloud-service-rest-api-using-oauth

Oracle Process Cloud service (PCS) はREST APIを提供しており、これを使って他のアプリケーションをPCSと統合できます。REST APIの詳細はリファレンスを参照ください。

REST API for Oracle Process Cloud Service, Version 4.0
https://docs.oracle.com/en/cloud/paas/process-cloud/cprrb/index.html

Oracle Process Cloud ServiceのREST APIは基本認証だけでなく、OAuthトークンを利用することもできます。このエントリでは、OAuthトークンを使ってPCSのREST APIにアクセスし、プロセスの新規インスタンスを作成する方法をご紹介します。

このエントリで説明するシナリオは、JCS-SXにデプロイ済みのWebアプリケーションが、PCSにデプロイ済みのビジネスプロセス("Funds Transfer Process") を呼び出すというものです。この"Funds Transfer"プロセスは、シンプルなプロセスで、リクエストメッセージに含まれるある属性を検証し、必要に応じて人による承認へと進めるものです。このWebアプリケーションはOAuthサーバからOAuthトークンを取得し、トークンを認証のためにPCS REST APIに渡します。

下図はJCS-SX、PCS、OAuthサーバ間のやりとりの概要を図示したものです。

このユースケースでは、JCS-SXインスタンスとPCSインスタンスがともに同じアイデンティティドメインでプロビジョニングされている前提です。同一アイデンティティドメインでプロビジョニングされる場合、OAuthを使った通信に必要なリソースやクライアントはトークン取得のために利用するOAuthサーバと一緒に自動的に構成されます。マイサービス（My Services）のOAuth管理（OAuth Administration）タブを開き、以下のOAuthリソースおよびデフォルトで登録済みのクライアントを確認できます。詳細は以下のURLをご覧ください。

Oracle® Cloud Administering Oracle Cloud Identity Management Release 17.2
Managing OAuth Resources and Clients
https://docs.oracle.com/en/cloud/get-started/subscriptions-cloud/csimg/managing-oauth-resources-and-clients.html

Note: OAuth管理にアクセスするためには、アイデンティティドメイン管理者ロールが必要です。

Note: クライアント識別子（Id、上図の赤枠で囲んだ部分）および、JCS-SX OAuthクライアントの［機密の表示］（Show Secret）をクリックすると確認可能なIdに対応する機密 (secret) は、Webアプリケーションがクライアントのアクセストークン取得ならびにPCS REST APIのアクセスするために利用します。

JCS-SX OAuthクライアントを使って、PCS REST APIをWebアプリケーションから呼び出すため、PCSリソースがクライアントからアクセス可能であることを確認しておきましょう。リソースへのアクセス可否は、［クライアントの登録］セクションのJCS-SX OAuthクライアントで、アクションパレット内の変更（Modify）メニューをクリックすることで管理できます（下図）。

Note: このエントリでは、ビジネスプロセス（Funds Transfer Process）をPCSにデプロイされていることを前提とします。参考のためにAppendixセクションにこのビジネスプロセスのエクスポート・アーカイブがあります。

前提条件が整えば、WebアプリケーションがPCS REST APIを呼び出すために使うクライアントアクセストークンの取得に取りかかることができます。このサンプルでは、OAuthグラントタイプ（クライアント資格証明とパスワード）を使い、以下の手順でクライアントアクセストークンを取得します。

クライアント資格証明を使ってクライアントアサーションを取得
取得したクライアントアサーションを使ってアクセストークンを取得

Note: Oracle Platform Service内でWebサービスを呼び出す場合、OWSMポリシーを使えばID伝播を実現でき、明示的にOAuthトークンを処理する必要はありません。今回はOAuthトークンを使ってPCSで認証するための説明を目的としているため、OWSMポリシーを使いません。

これらの手順を具体的なコード・スニペットを使って詳細に説明します。

呼び出し対象のビジネスプロセスの詳細情報と、OAuthトークンサーバへアクセスするために必要な詳細情報をHashMapに保存します。

Note: 説明の都合上、クライアント機密、ユーザー名、パスワードはjava.HashMapに格納していますが、資格証明の安全な管理を確実にするためには、Oracle Credential Store Framework (CSF) の利用を強く推奨します。文末のReferencesセクションから詳細情報を確認してください。

public static HashMap populateMap() {  
    HashMap map = new HashMap();  
    // PCS  
    map.put("PCS_URL", "https://<PCS_HOST>:443/bpm/api/3.0/processes");  
    map.put("PCS_PROCESS_DEF_ID", "default~MyApplication!1.0~FundsTransferProcess");  
    map.put("PCS_FTS_SVC_NAME", "FundsTransferProcess.service");  
    // OAuth  
    map.put("TOKEN_URL", "https://<ID_DOMAIN_NAME>.identity.<DATA_CENTER>.oraclecloud.com/oam/oauth2/tokens");  
    map.put("CLIENT_ID", "<CLIENT_ID>");  
    map.put("SECRET", "<SECRET>");  
    map.put("DOMAIN_NAME", "<ID_DOMAIN_NAME>");  
    map.put("USER_NAME","<PCS_USER_NAME>");  
    map.put("PASSWORD","<PCS_USER_PWD>");  
    return map;  
}  

public String getOAuthToken() throws Exception {  
    String token = "";  
    String authString = entryMap.get("CLIENT_ID")+":"+entryMap.get("SECRET");  

    Map clientAssertionMap = getClientAssertion(authString);  
    token = getAccessToken(authString,clientAssertionMap);  

    return token;  
}

Note: 上記コードで指定した、PCS_PROCESS_DEF_IDおよび PCS_FTS_SVC_NAME をキーとする値は参考のためです。PCSにfunds transferビジネスプロセスをデプロイした後、以下のcURLコマンドを実行してビジネスプロセスの詳細を取得できます。取得した値を使って置き換えてください。

curl -u <PCS_USER_NAME>:<PCS_USER_PWD> -H "Content-Type:application/json" -H "Accept:application/json" -X GET https://<PCS_HOST>:443/bpm/api/4.0/process-definitions

getOAuthTokenメソッドは、OAuthサーバ（トークンエンドポイント）へアクセスし基本認証ヘッダとしてclient_id:client_secret を渡すことで、クライアントアサーションを取得するための実装です。これらの詳細情報は、前述のOAuth管理タブから取得できます。以下のコードスニペットはその実装例です。
（訳注）
原文ではJerseyに依存するコードを使っていますが、JAX-RS 2.0ベースに書き換えています。

private Map<String, String> getClientAssertion(String authString) throws Exception {

    MultivaluedHashMap<String, String> formData = new MultivaluedHashMap();
    formData.putSingle("grant_type", "client_credentials");

    Response response
         = ClientBuilder.newClient()
                        .target(entryMap.get("TOKEN_URL").toString())
                        .request()
                        .header(HttpHeaders.AUTHORIZATION, "Basic " + DatatypeConverter.printBase64Binary(authString.getBytes("UTF-8")))
                        .header(HttpHeaders.CONTENT_TYPE, "application/x-www-form-urlencoded;charset=UTF-8")
                        .buildPost(Entity.entity(formData,
                                                 MediaType.APPLICATION_FORM_URLENCODED_TYPE))
                        .invoke();
    if (response.getStatus() != Response.Status.OK.getStatusCode()) {
        throw new Exception(response.getStatusInfo().getReasonPhrase());
    }

    Map<String, String> assertionMap = new HashMap<>();
    try (JsonReader reader = Json.createReader(new StringReader(response.readEntity(String.class)))) {
        response.close();
        JsonObject jsonObj = reader.readObject();
        assertionMap.put("assertion_token", jsonObj.get("access_token").toString());
        assertionMap.put("assertion_type", jsonObj.get("oracle_client_assertion_type").toString());
    }
    return assertionMap;
}

上記のコードでは、Jerseyクライアントを使ってトークンサーバにアクセスし、クライアントアサーションとクライアントアサーションタイプを取得するとともに、ペイロード内でgrant_type:client_credentialsも渡しています。以下のコードスニペットでは、password grant_typeを使い、ユーザー名とパスワードを先ほど取得したクライアントアサーションとともに渡すことで、クライアントアクセストークンをトークンサーバから取得しています。

private String getAccessToken(Map clientAssertionMap) throws Exception {

    MultivaluedHashMap<String, String> formData = new MultivaluedHashMap();
    formData.putSingle("grant_type", "password");
    formData.putSingle("username", entryMap.get("USER_NAME").toString());
    formData.putSingle("password", entryMap.get("PASSWORD").toString());
    formData.putSingle("client_assertion_type", clientAssertionMap.get("assertion_type").toString());
    formData.putSingle("client_assertion", clientAssertionMap.get("assertion_token").toString());

    Response response =
        ClientBuilder.newClient()
                     .target(entryMap.get("TOKEN_URL").toString())
                     .request()
                     .header(HttpHeaders.AUTHORIZATION, "Basic " + DatatypeConverter.printBase64Binary(authString.getBytes("UTF-8")))
                     .header(HttpHeaders.CONTENT_TYPE, "application/x-www-form-urlencoded;charset=UTF-8")
                     .buildPost(Entity.entity(formData, MediaType.APPLICATION_FORM_URLENCODED_TYPE))
                     .invoke(Response.class);

    if (response == null || response.getStatus() != Response.Status.OK.getStatusCode()) {
        throw new Exception(response.getStatusInfo().getReasonPhrase());
    }

    String accessToken;
    try (JsonReader reader = Json.createReader(new StringReader(response.readEntity(String.class)))) {
        response.close();
        JsonObject jsonObj = reader.readObject();
        accessToken = jsonObj.getString("access_token");
    }
    return accessToken;
}

これでクライアントアクセストークンを使ってPCSリソースにアクセスできるようになりました。以下のコードスニペットは、PCS REST APIを呼び出し、Funds Transferビジネスプロセスの新規プロセスインスタンスを生成しようとしています。ペイロードには、インスタンス作成対象のプロセス情報（定義ID、サービス名など）と、JSPページでユーザーが入力した入力パラメータが含まれています。先ほどの手順で取得したOAuthトークンをAuthorizationヘッダーに設定していることに注意してください。

public String invokeFundsTransferProcess(String token, FundsTransferRequest ftr) throws Exception {

    JsonObject postObj =
        Json.createObjectBuilder()
            .add("processDefId", entryMap.get("PCS_PROCESS_DEF_ID").toString())
            .add("serviceName", entryMap.get("PCS_FTS_SVC_NAME").toString())
            .add("operation", "start")
            .add("action", "Submit")
            .add("params",
                Json.createObjectBuilder()
                    .add("incidentId", ftr.getIncidentId())
                    .add("sourceAcctNo", ftr.getSourceAcctNo())
                    .add("destAcctNo", ftr.getDestAcctNo())
                    .add("amount", ftr.getAmount())
                    .add("transferType",
                            ftr.getTransferType()
                            .equals("tparty") ? "intra" : "inter"))
            .build();

    Response response =
        ClientBuilder.newClient()
                     .target(entryMap.get("PCS_URL").toString())
                     .request(MediaType.APPLICATION_JSON_TYPE)
                     .header(HttpHeaders.AUTHORIZATION, "Bearer " + token)
                     .buildPost(Entity.entity( postObj.toString(),
                                               MediaType.APPLICATION_JSON_TYPE))
                     .invoke(Response.class);

    if (response != null && response.getStatus() != Response.Status.OK.getStatusCode()) {
        throw new Exception(response.getStatusInfo().getReasonPhrase());
    }
    return String.valueOf(response.getStatus());
}

シンプルなJSPページを使ってユーザー入力を捕捉し、Funds Transferビジネスプロセスを起動します。

Funds Transferプロセスを開始出来た場合、下図のように、PCSのTrackingページで、生成済みかつ実行中のプロセスインスタンスを確認できます。

Known Issues:

ご利用のJDKによっては、PCS REST APIをJCS-SXから呼び出した場合に「javax.net.ssl.SSLHandshakeException: server certificate change is restricted during renegotiation」というエラーが出る可能性があります。その場合には、回避策として、JCS-SXの以下のシステムプロパティを設定して、サーバーを再起動してください。