Postmanを使ってSalesforce APIにアクセスする (特別なシナリオの OAuth 2.0 ユーザ名パスワードフローの場合)

ご存知の通り前置きが長いです。PostmanでSalesforceの認証を行う設定をとっとと見せろという方はPostman の認証用 API接続設定はこうだへどうぞ。接続アプリケーションを忘れずにね。

さて、便利ですね "Postman" 便利です。
使えば使うほど、ああ、これだけで良かったみたいにもなります。

さて、われらがノーコード・ローコードの代表 Salesforce さんですが、APIサービスとしても優れています。SOAP/XML, REST/JSON|XMLといった一般的なデータ送受のみならず、カスタマイズされた構成をメタデータをやり取りできたり、BayeuxベースのStreaming APIも利用できます。

このふんだんなAPIサービスを利用するためのWorkbenchという専用のツールもあります。これだけで、ほとんどすべてのAPIをテストしたりできて、ひじょーに便利です。APIでアクセス可能かどうかの検証や、APIコールの結果を実際にRAWデータで確認もできます。とはいえ、あくまでもAPIアクセス検証ツール的なものなので、独自のテストやルーチンを回すには向きませんね。ちょろっと使うには最高なんです。

ということで、"Postman" です。はいきた。これで利便性が高まるのは確定です。どのようにすれば"Postman"からSalesforceへアクセスできるか。今日は「Postmanでusername/password でアクセスしてみた編」です。

まずはともかく Salesforce で「接続アプリケーション」を作ろう

Salesforceは、特定の外部アプリケーション以外のAPIクライアントを受け付けてくれません。ついでにいうと、標準状態だと、Salesforceから外部へも接続できません。リモートサイトを使って定義しなければなりません。

接続アプリケーションの作り方は、こちらに詳しいです。今回のようにAPIで接続する場合には、API インテグレーション用の OAuth 設定の有効化が必要です。

実際に設定する画面は、次のとおりです。赤い線のついてる必須項目だけ入力してあげればよいということと、「OAuth 設定の有効化」にチェックをつけることです。

ここで、忘れずに設定しなければならないことはもう一つ。実際に利用するAPIにあわせて「選択した OAuth 範囲」を定義することです。「full」でええやんけと思われるかもしれませんが、次の点は注意ポイントです。

full は更新トークンを返しません。更新トークンを取得するには、refresh_token の範囲を明示的に要求する必要があります。

まぁ何でもかんでもじゃなくて、必要なものだけにしましょう。

認証を行うための認証フローは多くあり、全てはOAuth 認証フローで明記されています。このうちサーバ間インテグレーション用の OAuth 2.0 JWT ベアラーフローや特別なシナリオの OAuth 2.0 ユーザ名パスワードフロー などを利用する場合は、コールバックURL は不要です。そういった場合は「https://localhost:8443/RestTest/oauth/_callback」というようなhttpsの適当なURLを入れておきましょう。

全部入れたら「保存」です。

Postman の認証用 API接続設定はこうだ

今回は特別なシナリオの OAuth 2.0 ユーザ名パスワードフローで"Postman"を設定してみます。

Postmanで設定が必要なのはBodyとTestsだけです(もちろんURLもいるんだけど)。

その前に、さっき作成した「接続アプリケーション」を「参照」で開いてみましょう。このような画面が出てきます。重要なのは「コンシューマ鍵」と「コンシューマの秘密」です。コピペの準備をしておきましょう。Summer'20からでしょうか、いずれの項目もCopyってボタンついてます。ありがたい。

コピペの準備ができたら、Postmanを設定します。SalesforceのOAuth認証フローで利用するURLは https://login.salesforce.com/services/oauth2/token です。「私のドメイン」を設定して、login.salesforce.comからのログインは拒否している場合は、該当のドメインにしましょう。HTTPメソッドは「POST」です。

次にBody部分です。form-dataでもx-www-form-urlencodedでも、いずれでも良いので、次の5項目を入れましょう。

client_id:
client_secret:
grant_type:password
username:
password:

• client_id: 先程の接続アプリケーションで表示されていた「コンシューマ鍵」です
• client_secret: 先程の接続アプリケーションで表示されていた「コンシューマの秘密」です
• grant_type: password 固定です。OAuthフローごとに名称が変わります
• username: ログイン時のユーザ名です
• password: ログイン時のユーザのパスワードです。信頼できるIPアドレス外からのアクセスや、2FAが設定されているような場合には、パスワードのあとにセキュリティトークンが必要です。認証エラーで「セキュリティトークンが必要です」と言われたらつければよいです。だいたい必要です。

最後がTests部分です。ここは、認証済みのアクセストークンを再利用しやすいように、ログインが成功したときのアクセストークンを環境変数に保管します。

const json = JSON.parse(responseBody)
const ok = responseCode.code === 200

if (ok) {
    pm.globals.set('access_token',json.access_token)
    pm.globals.set('id', json.id)
}

ここまで設定できたら「Send」してみます。うまく設定できていれば、こんな感じでaccess_tokenを始めとした、いくつかの情報が返却されます。やったね。

この返り値の中のaccess_tokenとidが環境変数へ保管されています。

これらを使って、実際に認証済みの状態でアクセスするには次のようにします。URLになにも考えずに{{id}}、AuthorizationのTYPEをBearer Tokenにして、Tokenに{{access_token}}とそっと定義します。したらば「Send」です。

返却値には、対象ユーザの詳細情報がたくさん表示されているはずです。アクセストークンを使って、ただしくSalesforceのAPIへアクセスできましたね。

こんな感じで、Salesforce REST APIへアクセスするテストを実装していってみましょう。