CData Software Blog

クラウド連携のCData Software の技術ブログです。

CData NetSuite Driver 2020.2 バージョンでの変更点:OAuth・トークンベース認証の設定手順

f:id:sugimomoto:20201028120610p:plain

こんにちは。CData Software Japanリードエンジニアの杉本です。

今回の記事ではCData NetSuite Driverの重要な変更点についてのお知らせです!

最新のCData NetSuite Driverでは、NetSuite APIの最新バージョン「2020.2」に対応しました。

www.netsuite.com

f:id:sugimomoto:20201028120300p:plain

CData NetSuite Driverでは、接続文字列オプションの一覧にある「Version」から、接続対象となっているNetSuite APIバージョンを確認できます。

f:id:sugimomoto:20201028120309p:plain

このバージョンで最も重要なアップデートは「NetSuite ReleaseNotes_2020.2.0_ja_JP.pdf」の83~84ページに掲載されている「ユーザー資格情報からのSOAP Webサービス認証の廃止」です。

f:id:sugimomoto:20201028120316p:plain

NetSuite DriverではSuiteTalkと呼ばれるSOAPベースのAPIを軸として機能を提供しているのですが、この2020_2 バージョンからUserId・PWを用いたAPI接続ができなくなりました。

詳しくは以下の主要な変更点をご覧ください。

http://cdn.cdata.com/help/DNF/jp/odbc/pg_changes.htm

ログインとセッションの変更の廃止

NetSuiteの2020.1リリース以降、ログイン/ログアウト要求を介してAPIとのセッションを確立できなくなりました。 これにより、接続プロパティUseSessionsが廃止されたため、削除する必要がありました。 これは、セッションの同時実行性を利用するために使用される個々の統合を強制するNetSuiteの変更の一部です。 これは、ユーザー認証とパスワード認証を同時にリクエストと一緒に使用することができなくなったことを意味します。

代わりに、同時リクエストを利用したい場合は、トークンベースの認証またはOAuthを使用する必要があります。 現在ユーザー/パスワードを使用している場合は、OAuth認証の使用への切り替えを確認することをお勧めします。 NetSuiteで統合を作成したら、統合に指定したものと一致するようにMaximumConcurrentSessionsを設定するだけです。

そのため、この記事ではこの変更により発生する問題、およびその対処方法について、お伝えします。

接続例にはCData JDBC Driverを用いていますが、ODBCADO.NETExcel Add-inなど、すべて共通となります。

既存の認証方法で2020_2 バージョンのAPIに接続した場合どうなるのか?

まず、既存のユーザーID・PWを用いた認証では具体的にどんな問題に遭遇するのか? 問題が発生するユーザーID・PWと2020_1バージョンのAPIを用いて確認してみましょう。

なお、接続に成功した場合は、以下のようにNetSuite上のテーブル(エンティティ)一覧とそのデータが取得できます。

f:id:sugimomoto:20201028120322p:plain

エラーが発生する指定ですが、以下のようにUser・Passwordの項目と共にVersionの項目で「2020_2」を指定します。

プロパティ名 備考
AccountId YOUR_ACCOUNTID 接続対象のNetSuite AccountIDを指定します。
User Your_Username API接続に使用するユーザーのIDを指定します。
Password Your_Password API接続に使用するユーザーのパスワードを指定します。
Version 2020_2 エラーを確認するために最新バージョン「2020_2」を指定します。

これで接続を試してみると、以下のように「Invalid authentication.」エラーが発生しました。

f:id:sugimomoto:20201028120329p:plain

これが最新バージョンのAPIでUser・Passwordによる認証ができない場合のエラーメッセージになります。

具体的なエラーレスポンスは以下のようになっています。

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Body>
        <Fault>
            <faultcode>
                soapenv:Server.userException
            </faultcode>
            <faultstring>
                Invalid authentication.
            </faultstring>
            <detail>
                <invalidSessionFault xmlns:platformFaults="urn:faults_2020_2.platform.webservices.netsuite.com">
                    <code>
                        USER_ERROR
                    </code>
                    <message>
                        Invalid authentication.
                    </message>
                </invalidSessionFault>
                <hostname xmlns:ns1="http://xml.apache.org/axis/">
                    partners018
                </hostname>
            </detail>
        </Fault>
    </Body>
</Envelope>

ちなみにVersionだけ「2020_1」に変更すると、以下のように接続することが可能です。

プロパティ名 備考
AccountId YOUR_ACCOUNTID 接続対象のNetSuite AccountIDを指定します。
User Your_Username API接続に使用するユーザーのIDを指定します。
Password Your_Password API接続に使用するユーザーのパスワードを指定します。
Version 2020_1 User・Passwordによる接続が可能な「2020_1」を指定します。

f:id:sugimomoto:20201028120336p:plain

2020_2 バージョンのAPIに変更する場合に必要な対処方法

具体的なエラー内容がわかったところで対象方法を確認してみましょう。

NetSuite DriverではUser・Passwordによる認証を含めて、現在3種類の認証方法をサポートしています。

認証方法 概要 備考
ユーザー資格情報認証 User・Passwordによる接続方法 2020_1まで利用可能。
OAuth認証 OAuthの統合設定を作成し、ブラウザログインを用いて接続する方法 2020_1以前、2020_2以降も利用可能。
トークンベース認証 OAuthの統合設定を作成し、NetSuiteの管理画面からユーザーに紐付いたTokenを生成して接続する方法 2020_1以前、2020_2以降も利用可能。

2020_2以降のバージョンで接続する際には、OAuth認証トークンベース認証を用いた接続への切替が必要となります。すでにこのOAuth認証もしくはトークンベース認証を使用していれば、特に設定の変更は必要ありません。

ちなみに、OAuth認証では、接続時にブラウザによるユーザーのログインとアクセス許可を求めるアプローチとなるため、そういったUIによる設定が可能な環境やアプリケーションで実施する必要があります。

環境によってはOAuthがやりづらいことがあると思うので、その場合はトークンベース認証を行うのが良いでしょう。

OAuth認証

それではまずOAuth認証を試してみましょう。

cdn.cdata.com

OAuth認証を行うためには、対象のNetSuiteの環境にて「統合」の設定を追加する必要があります。

NetSuiteにログインして、設定マネージャーに移動し、インテグレーションの「統合を管理」から「新規作成」をクリックします。

f:id:sugimomoto:20201028120346p:plain

統合作成画面では、以下のように設定を行います。

プロパティ名 備考
名前 目的や役割など、任意の名前を入力してください。
トークンベース認証:トークンベース認証 チェックをいれてください。
トークンベース認証:TBA:認証フロー チェックをいれてください。
トークンベース認証:CALLBACK URL コールバック先のURIを指定します。ローカルのドライバーに接続する場合はhttps://localhost:33333 などと入力します。
OAuth 2.0:承認コード付与 チェックは不要です。

f:id:sugimomoto:20201028120435p:plain

必要なプロパティを入力後、保存をクリックすることで、接続の際に必要となるコンシュマーキー(消費者とついていますが)とコンシュマーシークレットが入手できます。

これは初回しか表示されないので注意しましょう。

f:id:sugimomoto:20201028120401p:plain

あとは、生成されたコンシュマーキーとコンシュマーシークレットを用いて、以下のようにDriverの接続プロパティを入力するだけです。

プロパティ名 備考
AccountId YOUR_ACCOUNTID 接続対象のNetSuite AccountIDを指定します。
OAuthClientId 4dbf276b1914f991614977a46350b683699e47d9767d7344928d18b462152933 コンシュマーキー・クライアントIDを指定してください。
OAuthClientSecret d19052f565f1329adbf4ece9a42f82206a1e27cb240f9dcbc34064561d7eace2 コンシュマーのシークレット・クライアントシークレットを指定してください。
CallbackURL https://localhost:33333 Redirect URIを指定してください。HTTPSを指定する必要があります。
InitiateOAuth GETANDREFRESH 固定でGETANDREFRESHを指定します。
Version 2020_2 最新バージョンのDriverではデフォルトが2020_2になっています。

これでログインを試みると、以下のようにブラウザが立ち上がり、アクセス許可を求める画面が表示されます。内容を確認して、許可をクリックしてください。

f:id:sugimomoto:20201028120408p:plain

接続完了後、データにアクセスができるようになります。

f:id:sugimomoto:20201028120425p:plain

トークンベース認証

トークンベース認証は、OAuth認証を土台としながら、予めNetSuiteの管理画面からアクセス用のトークンを取得して接続する方法です。

http://cdn.cdata.com/help/DNF/jp/odbc/pg_createinui.htm

実はOAuth認証でも内部ではトークンの取得を行っているので、UI上で予め作成するのか、プログラム側で任意のユーザーを選ばせるのか?だけの違いしかありません。

手順はOAuthの時と同じように、予め「統合」の設定を作成しておく必要があります。

プロパティ名 備考
名前 目的や役割など、任意の名前を入力してください。
トークンベース認証:トークンベース認証 チェックをいれてください。
トークンベース認証:TBA:認証フロー チェックをいれてください。
トークンベース認証:CALLBACK URL コールバック先のURIを指定します。ローカルのドライバーに接続する場合はhttps://localhost:33333 などと入力します。
OAuth 2.0:承認コード付与 不要です。

f:id:sugimomoto:20201028120435p:plain

統合を作成後、同じようにコンシュマーキーとコンシュマーシークレットが表示されるので、控えておきましょう。

f:id:sugimomoto:20201028120444p:plain

次にロールの管理画面から、新しいロール・もしくは既存のロールを編集し、トークンベース認証に必要な設定を付与します。

必要な設定は「SOAP Webサービス」「アクセストークンの管理」「ユーザーアクセストークン」の3種類です。そして、このロールをトークンベース認証で接続するユーザーに付与してください。

f:id:sugimomoto:20201028120451p:plain

最後にユーザー/ロールの「アクセストークン」画面から新しいアクセストークンの作成を行います。

予め作成したアプリケーションを選択し、先程構成したロールおよびそのロールが紐付けられたユーザーを選択して、保存します。

f:id:sugimomoto:20201028120459p:plain

保存が完了すると、以下のトークンIDとトークンシークレットが表示されるので、これを控えておきます。

f:id:sugimomoto:20201028120506p:plain

あとは接続プロパティで生成した情報を以下のように設定するだけです。

プロパティ名 備考
AccountId YOUR_ACCOUNTID 接続対象のNetSuite AccountIDを指定します。
OAuthClientId bc0d8135658e8e73e3bbed2e7bdd7868f632c62c76b66b2ed490c43eadb78087 コンシュマーキー・クライアントIDを指定してください。
OAuthClientSecret 4087ce64b51bbda2e2e005b824186c1303641d223b7cfcc7eedad708e7d129dc コンシュマーのシークレット・クライアントシークレットを指定してください。
OAuthAccessToken 2dc7bdc6f666ad27db54fabc7d1a44a1dc72f9051b8f1510bb90cfde19af8600 トークンIDを指定してください。
OAuthAccessTokenSecret 90b1d05c1389c6c7e913a0488b6f48c7199d56385042e2580901e00bc286f40e トークンシークレットを指定してください。
Version 2020_2 最新バージョンのDriverではデフォルトが2020_2になっています。

今回はOAuth認証の時のように、ブラウザを用いたログインは行われず、そのまま接続が完了します。

f:id:sugimomoto:20201028120511p:plain

補足① 以前のバージョンについて

ユーザーID・PWが利用できる2020_1までのバージョンですが、現状すぐに廃止されるわけではないようです。

2020/10/28 時点で公式のヘルプを参照したところ、SuiteTalk 2009.2のバージョンのサポートは終了するようですが、2020.1 については現在触れられていませんでした。

f:id:sugimomoto:20201028120518p:plain

補足② UseSessionsプロパティの廃止について

このバージョンの変更に伴い、CData NetSuite Driver 2019バージョンまで提供していたUseSessionsプロパティが廃止になりました。

f:id:sugimomoto:20201028120525p:plain

今後はMaximum Concurrent Sessionsのプロパティのみ使用しますが、2020_1のバージョンからはAccountId・ApplicationIdに基づいて自動的に設定されます。

http://cdn.cdata.com/help/DNF/jp/odbc/RSBNetSuite_p_MaximumConcurrentSessions.htm

f:id:sugimomoto:20201028120531p:plain

おわりに

おそらく今まではユーザーID・PWによる接続を行っている方々がほとんどかと思いますので、かなり影響が大きい変更になっていました。

すぐに使えなくなる機能ではありませんが、最新バージョンのDriverを利用する際にはご注意ください。

また、もし本内容についてご質問・ご相談がありましたら無償のテクニカルサポートまでお気軽にお問い合わせください。

https://www.cdata.com/jp/support/submit.aspx