2021.03.29

OAuthのJWTベアラーフローを用いてSalesforceに接続する

  • このエントリーをはてなブックマークに追加
  • follow us in feedly
gettyimages (19981)

はじめに

ここ数年で、システム開発者ではない一般の方でも、API(アプリケーションプログラミングインタフェース)という言葉を聞いたことがあるのではないでしょうか。
これは、QRコード決済などの電子決済が身近になったことや、スマートフォンのアプリを利用することが増え、認証操作に触れる機会が増えたことが要因であると考えられます。
例えば私が関わることの多い金融業界でも、オープンAPIという大号令があり、API連携を行うシステム・技術は今後ますます重要になるでしょう。

さて、このAPI利用に関して、Salesforceにはかなりの機能・サービスがSalesforce標準として用意されています。
例えば、Salesforceオブジェクト(テーブル)の構築と、プロファイル設定などのセキュリティ設定を行うことですぐに利用できるSOAP/REST APIによるデータ取得機能や、そのAPIを利用するためのOAuth認証機能などです。

このOAuth機能の概要については、下記記事をご参照頂ければ、と思います。
今回は、このSalesforceのOAuth機能に関して、① APIを利用するために必要な認証の仕方、② APIによりデータを取得する方法、の2つの流れを簡単に説明いたします。
特に①の認証方法については、特にシステム間連携で利用が推奨される方式であるものの、やや取っ付き難い、OAuth 2.0 JWT ベアラーフローについて、簡単に説明しようと思います。

OAuthのおさらい

まずは、OAuthについておさらいします。

OAuthを簡単に説明すると、あるリソースを利用するための、認証と認可を司る仕組みです。
具体的には、OAuthの機能を利用することで、認証結果を示すアクセストークンという鍵のような文字列を取得することができ、そのアクセストークンを用いることで認可された操作を実行できるようになります。

例えば、ある特定のSalesforceユーザが参照可能なデータ、言い換えると、参照権限が付与されたデータについて、API機能により取得したい(公開させたい)場合を想定します。
このときOAuthを利用して、”ある特定のSalesforceユーザ”を指定した認証と、”参照権限が付与されたデータをAPI機能により取得する”という操作への認可を与えることができます。

Salesforceのエンジニアは、VS Codeなどによる開発時、以下のような画面を見たことがあるのではないでしょうか。
これもまさにOAuthの仕組みを用い、開発対象のSalesforce組織への認証を行うとともに、開発に必要な機能への認可を要求するものとなります。
この裏側で、アクセストークンのやり取りがなされているものです。

VS Code認可イメージ

OAuth 2.0 JWT ベアラーフロー とは

OAuth 2.0 JWT ベアラーフローは、Salesforceで利用できる認証フローのうちの1つとなります。
その他のフローや、各フローの概要については、上記の弊社Blog記事や下記SalesforceのHelp(※)などを参照いただければと思います。

このフローを選択する条件としては、その認証を行う場にユーザがいるかいないか、自動的な認証をしたいかどうか、によります。
もし、システム間連携であり、認証・接続毎にユーザ操作を行うことができないのであれば、当フローが第1候補となると思います。
以下に、Salesforceで利用できる各認証機能を選択するための簡単なフローチャートを記載してみます。

各認証機能を選択するためのフローチャート

※ご参考

認証に用いる秘密鍵・証明書の作成

OAuth 2.0 JWT ベアラーフローでは、JWTという電子署名の仕組みを用いたデータのやり取りを行うことで、アクセス元の認証を行います。
このJWTは、JSON Web Tokenの略でジョットと読みます。
JWTを用いるには、署名のための証明書と、その証明書に紐付く鍵を用意する必要があります。

ここでは、この証明書作成や、紐付く鍵の作成方法について詳細には述べませんが、個人的な開発・検証で利用するような自己署名証明書であれば、opensslコマンドなどの機能を用いて簡単に作成することができます。(※)
ここでは、以下のようにopensslコマンドを利用し、証明書(crtファイル)と秘密鍵(pemファイル)を作成することとします。

※ただし、正式なサービスで利用する場合は、公式な認証局から証明書を発行して貰うなどの検討をしてください。
openssl genrsa -out test.pem 2048
秘密鍵(test.pem)の作成
openssl req -new -key test.pem -out test.csr
証明書署名要求(test.csr)の作成
openssl x509 -req -days 365 -in test.csr -signkey test.pem -out test.crt
サーバ証明書(test.crt)の作成
作成した秘密鍵(test.pem)と、サーバ証明書(test.crt)は、後ほど利用します。

Salesforce(サーバ)の設定

次に、OAuthのリソースサーバ・認可サーバを担う、Salesforce側の設定を行います。

権限設定

まずは、今回追加するOAuthフローを利用するユーザを設定します。
この利用ユーザの指定については、Salesforceのプロファイルか、権限セット機能を用いて行います。

今回はプロファイルを用いることとします。
OAuth利用対象プロファイルを決め、そのプロファイルに必要となるレコード参照権限や項目レベルセキュリティ設定を行います。
また、そのプロファイルの「システム権限」設定のうち、「APIの有効化」権限を付与します。
このSalesforce上の設定について、1つ注意事項があります。
Salesforceにおいて、そのプロファイルや権限セット、項目レベルセキュリティの設定によるレコード参照や項目参照権限の設定は、エンジニアや管理者にとって特に注意を要するところではあります。
しかし、特にこの「API の有効化」権限を有効にする場合は、更なる注意が必要です。

前述した、オブジェクトの構築によりすぐにSOAP/REST APIによるデータ取得が利用できるというSalesforceの機能は、セキュリティ観点からすると諸刃の剣となります。
当該権限を付与したユーザからのアクセス・認証後のアクセスには限定され、かつ、対象ユーザに付与された参照権限には限定されますが、”レコード参照や項目参照権限をきちんと設定しないと、意図しないデータ参照が可能になる”、ということが発生し得ます。

特に、「API の有効化」により自動的に利用可能となるSalesforce標準APIの中には、SQLに良く似たSOQL言語を用いてデータクエリ取得を可能とするAPIも含まれますので、Salesforce上のレコード参照・項目参照権限をきちんと制限することが重要です。

接続アプリケーション設定・証明書登録

次に、「接続アプリケーション」設定を行います。
「接続アプリケーション」とは、OAuthのような外部からSalesforceにアクセスするアプリケーションに対し、どのような認証方法を行うのか、また、どのような権限を認可するのか、を一元管理する設定です。

「設定」画面を開き、設定の検索メニューより「アプリケーションマネージャ」メニューを選択します。
メニュー内の右上に「新規接続アプリケーション」ボタンがありますので、押下します。

編集画面にて、以下設定を行います。その他設定はデフォルト値のままとします。
項目 設定値 補足
接続アプリケーション名 ※任意値 設定の表示名を管理するものです。
今回は「TEST_OAuth_JWT」と設定します。
API 参照名 ※任意値 設定のユニークな名前を管理するものです。
今回は「TEST_OAuth_JWT」と設定します。
取引先責任者 メール ※任意値
(メールアドレス)
問題発生時の連絡先となります。
今回は、自身のメールアドレスを設定します。
OAuth 設定の有効化 TRUE OAuthを利用するのでチェックを付けます。
コールバック URL https://example.com JWTべアラートークンフローでは
コールバックURLを用いないため、
設定しても他に影響しないURLを設定します。
デジタル署名を使用 TRUE 証明書を利用するのでチェックを付けます。
チェック後下部に表示されるアップロードボタンより、
前述の手順で作成した証明書(test.crt)を登録します。
選択した OAuth 範囲 ※補足に記載の
4権限を設定
・Web 経由のデータへのアクセスを提供 (web)
・データへのアクセスと管理 (api)
・ユーザに代わっていつでも要求を実行 (refresh_token, offline_access)
・基本情報へのアクセス (id, profile, email, address, phone)
上記を設定すると、以下のようなイメージになるはずです。
このまま保存してください。

新規接続アプリケーション

保存すると、以下のような画面になります。
この際、画面表示される「コンシューマ鍵」はこの後の手順で利用するため、書き留めておいてください。

接続アプリケーション保存後画面

先の画面上の上部「Manage」ボタンを押下し、追加設定を行います。
以下のよう、「許可されているユーザ」項目について、「管理者が承認したユーザは事前承認済み」へ変更し、保存してください。

manageボタン

接続アプリケーションの編集

最後に、当「接続アプリケーション」の利用を許可するユーザを選択します。
下記画像のように、「プロファイル」か「権限セット」によるユーザ絞り込み指定が可能です。
今回は、前述の手順で設定したプロファイルをここに指定することとします。

接続アプリケーション利用者の指定

以上で、OAuth 2.0 JWT ベアラーフローを利用してSalesforceへの認証・認可を行うためのSalesforce上での設定は完了です。
この後は、作成・設定した内容を元に、認証・認可結果を管理するアクセストークンを取得してみます。

認証・認可要求をするコード(クライアント)の作成

次に、Salesforceへの認証・認可要求をするクライアントを作成してみます。
昨今Lightning Web ComponentやSalesforce Functionsなどの新しい機能で利用される、我々Salesforceエンジニアに馴染み深いJavaScript/Node.jsを用いたクライアントとしてみます。
とは言っても、JWTの署名などの操作は、1からコーディングするのはなかなか厳しいものです。
このため、公開されているライブラリなどを利用した、Node.jsのコードを以下に用意しました。
上記コードをダウンロードし、実行のために、以下ソフトウェアをインストールします。
 ・Node.jsのインストール
 ・VS Codeのインストール

インストール後、ダウンロード先のフォルダ内で、「npm install」コマンドを実行します。
Node.jsのコードで必要になるライブラリを取得します。

その後、「/crt」ディレクトリに、先ほど作成した秘密鍵ファイル(.pem)を格納します。
サンプル用の「dummy.pem」ファイルを読み込むよう設定しているので、同名のファイルにリネームして格納するか、「index.js」内のファイル名指定箇所を作成した秘密鍵ファイル名に変更してください。

さらに、「login-info.json」ファイルに、検証をする対象のSalesforceのユーザ名、先ほどの「接続アプリケーション」設定で取得したコンシューマ鍵値を入力、保存します。
ログインURLは、Developer EditionのSalesforce組織での検証であれば、「https://login.salesforce.com」の指定のままで構いません。

ここまで来たら、後は実行します。VS Codeのデバッグ実行でコード実行できるように設定していますので、以下の画像のように、VS Code上のボタンを押下します。

VS Codeデバッグ実行

上記「プログラムの起動」ボタンを押下すると、下記のように、デバッグコンソール上に「access token」で示される文字列が取得されるはずです。
これが、OAuthの認証結果、認可された操作を可能とするアクセストークンとなります。

VS Codeデバッグ実行結果

VS Codeデバッグ実行結果(2)

簡単に、どのような情報をやり取りしているかと説明すると、以下属性情報(Claim)をJSON文字列として作成し、秘密鍵によるJWTトークン化・署名を行い、Salesforceに送信しているものとなります。
属性名 設定内容
sub 接続するSalesforceのユーザアカウント名
iss 接続アプリケーションのコンシューマ鍵
aud 対象ユーザのログインURL
exp トークンの有効期限(指定必須)
Salesforceは、JWTトークン内の情報を確認し、「接続アプリケーション」上の証明書を用いて真偽判断のうえ、問題ないと判断したらアクセストークンを返却します。

REST APIを利用して、データ取得要求をする

最後に、取得できたアクセストークンを用いて、Salesforce上のデータ取得を試してみましょう。
SalesforceのAPIは、下記、データ取得用のSOQLを発行できるQuery REST APIを利用することとします。
また、簡単にAPIを呼び出すツールとして、下記、Talend API Testerを利用することとします。
Talend API Testerに、以下のようなAPI呼び出し設定を入力します。
項目 設定値 補足
METHOD GET
SCHEME :// HOST https://<接続先Salesforceのドメイン>/services/data/v49.0/query/ 「①接続先組織ドメイン」と、「②Query APIサービス」の指定をします。
QUERY PARAMETERS  q=SELECT Id, Name FROM Account WHERE Name LIKE '%sForce%' ③「sForce」の文字列を含む「取引先」レコードの取得を指定します。
HEADERS Authorization : Bearer <前述の手順で取得したアクセストークン文字列> ④「Authorization」ヘッダーに、「Bearer」で始まる文字列を指定します。
「Bearer」とアクセストークン文字列の間には、1文字の半角スペースを入力してください。
上記入力の後、「Send」ボタンを押すと、下記画面のようにResponseが「200 OK」として返却されるはずです。
ResponseのBODYに、Query APIの検索結果であるレコード情報が表示されることが分かります。

REST API呼び出し結果(1)

REST API呼び出し結果(2)

REST API呼び出し結果(3)

おわりに

以上、駆け足ですが、SalesforceのOAuth機能に関して、① APIを利用するために必要な認証の仕方、② APIによりデータを取得する方法の2つの流れを説明しました。
本内容を以て、SalesforcenにおけるOAuth操作を学習するための取っ掛かりとしていただけますと幸いです。

今回はOAuthやJWTベアラーフローの技術的な詳細や、セキュリティに関する詳細な説明はしませんでしたが、利用するにあたっては自ら説明できるようになっておくことが重要です。
幸いさまざまなサイト・文献等がありますので、継続して学習していただければと思います。

※QRコードは(株)デンソーウェーブの登録商標です。
61 件
     
  • banner
  • banner

関連する記事